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

> Deploy Kimi Code in containerized environments easily. Follow our Docker and Kubernetes guide to build a container image and run the server quickly using production-ready Dockerfile and scripts.

- Repository: [Moonshot AI/kimi-code](https://github.com/MoonshotAI/kimi-code)
- Tags: how-to-guide
- Published: 2026-07-26

---

**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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/klient/scripts/run-docker-e2e.sh) — Build-and-run automation script
- [`packages/klient/package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/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:

```bash
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:

```bash
cd packages/klient
pnpm docker:e2e

```

This command executes [`scripts/run-docker-e2e.sh`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/run-docker-e2e.sh) uses these exact mounts:

```bash
-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:

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

```

### Complete Docker Run Example

Combine all parameters for a manual launch:

```bash
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`](https://github.com/MoonshotAI/kimi-code/blob/main/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

```yaml
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`](https://github.com/MoonshotAI/kimi-code/blob/main/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.