How to Deploy Kimi Code in Containerized Environments: Docker and Kubernetes Guide

Kimi Code ships with a production-ready Dockerfile and helper scripts that let you build a container image in minutes, mount the required data volumes, and run the server on port 58627 using either Docker CLI or Kubernetes manifests.

Kimi Code is a TypeScript monorepo developed by MoonshotAI that powers the kap-server back-end and client SDKs. Because the repository includes a purpose-built Dockerfile in packages/klient and automated build scripts, you can package the entire application into a portable container and deploy Kimi Code in containerized environments such as Docker Compose, Kubernetes, or CI/CD pipelines. This guide leverages the actual source assets from the MoonshotAI/kimi-code repository to ensure accurate, reproducible deployments.

Prerequisites and Repository Structure

Before building the image, ensure your environment meets the baseline requirements defined in the source code.

Node.js Version. The .nvmrc file specifies Node.js ≥ 24.15.0. The Dockerfile at packages/klient/Dockerfile inherits from the official Node 24 image to satisfy this constraint.

Package Manager. The monorepo uses pnpm workspaces orchestrated by pnpm-workspace.yaml. The Docker image preserves this workspace layout, allowing both packages/kap-server and packages/klient to coexist inside the container.

Required Files. You will reference these paths during deployment:

• packages/klient/Dockerfile — Base image definition with environment variables
• packages/klient/scripts/run-docker-e2e.sh — Build-and-run automation script
• packages/klient/package.json — Contains the docker:e2e npm script shortcut

Building the Kimi Code Docker Image

You have two methods to build the image: manual Docker commands or the provided helper script.

Manual Build

From the repository root, execute:

docker build -t kimi-code:latest -f packages/klient/Dockerfile .

This command targets the Dockerfile in packages/klient, tags the image as kimi-code:latest, and embeds the entire monorepo context.

Automated Build via npm Script

The repository provides a convenience script. If you have pnpm installed locally:

cd packages/klient
pnpm docker:e2e

This command executes scripts/run-docker-e2e.sh, which automatically builds the image (if missing) and starts the container with correct volume mounts.

Running Kimi Code in Docker Containers

To successfully deploy Kimi Code in containerized environments, you must mount three specific directories and expose the server port.

Required Environment Variables

The container expects these variables at runtime:

• KIMI_CODE_HOME — Isolated home directory for configuration, authentication, and caches
• KIMI_SERVER_E2E_REPORT_DIR — Destination for server-generated test reports
• TMPDIR — Temporary data location

Volume Mounts

Map host directories to the container paths defined above. The helper script run-docker-e2e.sh uses these exact mounts:

-v $(pwd)/docker-e2e/kimi-code-home:/data/docker-e2e/kimi-code-home \
-v $(pwd)/server-e2e-reports/docker/latest:/data/server-e2e-reports/docker/latest \
-v $(pwd)/docker-e2e/tmp:/data/docker-e2e/tmp

Port Exposure

The kap-server listens on http://127.0.0.1:58627 by default (controlled by KIMI_SERVER_URL). Publish this port when starting the container:

docker run -p 58627:58627 ... kimi-code:latest

Complete Docker Run Example

Combine all parameters for a manual launch:

docker run \
  -e KIMI_CODE_HOME=/data/docker-e2e/kimi-code-home \
  -e KIMI_SERVER_E2E_REPORT_DIR=/data/server-e2e-reports/docker/latest \
  -e TMPDIR=/data/docker-e2e/tmp \
  -v $(pwd)/docker-e2e/kimi-code-home:/data/docker-e2e/kimi-code-home \
  -v $(pwd)/server-e2e-reports/docker/latest:/data/server-e2e-reports/docker/latest \
  -v $(pwd)/docker-e2e/tmp:/data/docker-e2e/tmp \
  -p 58627:58627 \
  --rm \
  kimi-code:latest \
  bash -lc "pnpm --filter @moonshot-ai/kap-server start"

Replace the final command with npm run dev or any other entry point defined in your package.json.

Deploying Kimi Code to Kubernetes

The same Docker image runs in Kubernetes clusters. Translate the Docker volumes into PersistentVolumeClaims and pass environment variables via a ConfigMap or Secret.

Minimal Pod Specification

apiVersion: v1
kind: Pod
metadata:
  name: kimi-code
spec:
  containers:
  - name: server
    image: kimi-code:latest
    ports:
    - containerPort: 58627
      name: http
    env:
    - name: KIMI_CODE_HOME
      value: /data/kimi-code-home
    - name: KIMI_SERVER_E2E_REPORT_DIR
      value: /data/server-reports
    - name: TMPDIR
      value: /data/tmp
    volumeMounts:
    - name: home
      mountPath: /data/kimi-code-home
    - name: reports
      mountPath: /data/server-reports
    - name: tmp
      mountPath: /data/tmp
  volumes:
  - name: home
    persistentVolumeClaim:
      claimName: kimi-home-pvc
  - name: reports
    persistentVolumeClaim:
      claimName: kimi-reports-pvc
  - name: tmp
    emptyDir: {}

Expose the deployment through a Service of type LoadBalancer or ClusterIP depending on your cluster networking.

Configuration Quick Reference

Variable	Purpose	Example Path
KIMI_CODE_HOME	Isolated Kimi home (config, auth, caches)	/data/docker-e2e/kimi-code-home
KIMI_SERVER_E2E_REPORT_DIR	Server-side report storage	/data/server-e2e-reports/docker/latest
TMPDIR	Temporary file storage	/data/docker-e2e/tmp
KIMI_SERVER_URL	Server bind address	http://127.0.0.1:58627

Summary

• Build the image using docker build -f packages/klient/Dockerfile or run pnpm docker:e2e from packages/klient for automated setup.
• Configure three mandatory volume mounts for KIMI_CODE_HOME, KIMI_SERVER_E2E_REPORT_DIR, and TMPDIR to persist data outside the container.
• Expose port 58627 to reach the kap-server API from external clients.
• Orchestrate using Kubernetes by converting Docker volume mounts into PersistentVolumeClaims and mapping environment variables via ConfigMaps.
• Base all deployments on Node 24 (≥ 24.15.0) as specified in .nvmrc and implemented in the official Dockerfile.

Frequently Asked Questions

What is the default port for Kimi Code server?

The server binds to port 58627 by default, as defined by the KIMI_SERVER_URL environment variable inside packages/klient/Dockerfile. When deploying Kimi Code in containerized environments, expose this port via Docker's -p flag or Kubernetes containerPort to enable external access.

Can I run Kimi Code without the end-to-end test components?

Yes. While the provided Dockerfile resides in packages/klient and the helper script is named run-docker-e2e.sh, you can override the container entry point to start only the production server. Use bash -lc "pnpm --filter @moonshot-ai/kap-server start" instead of the e2e test runner command to launch only the kap-server process.

How do I persist data when the container restarts?

Mount the three required directories—KIMI_CODE_HOME, KIMI_SERVER_E2E_REPORT_DIR, and TMPDIR—to host volumes or PersistentVolumes. In Kubernetes, use PersistentVolumeClaim resources; in Docker, use -v volume mounts. This ensures configuration, authentication tokens, and reports survive container recreation.

What Node version is required to build the container?

The repository requires Node.js ≥ 24.15.0, specified in the .nvmrc file at the repository root. The Dockerfile uses the official Node 24 base image, so the container automatically satisfies this requirement without manual intervention.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}