# How to Run the Kimi-Code Development Server Locally: Complete Setup Guide

> Easily run the Kimi-Code development server locally with our complete setup guide. Follow simple steps to start the kap-server and access debug endpoints for efficient development.

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

---

**Run `pnpm dev:server` from the repository root after installing Node.js ≥24.15.0 and pnpm 10.33.0 to start the kap-server on http://127.0.0.1:58627 with debug endpoints enabled.**

The **kap-server** is the core development server that powers both the Kimi Code CLI (`kimi`) and the web UI (`kimi-web`). Learning how to run the kimi-code development server locally is essential for contributors who want to modify the agent's behavior, develop plugins, or test changes against a live backend before deployment.

## Prerequisites

Before launching the development server, verify your environment meets the minimum requirements specified in the MoonshotAI/kimi-code repository.

- **Node.js** ≥ 24.15.0
- **pnpm** 10.33.0

Check your versions with:

```bash
node --version   # → 24.15.x or higher

pnpm --version   # → 10.33.x

```

## Installation and Setup

Clone the repository and install workspace dependencies using pnpm.

```bash
git clone https://github.com/MoonshotAI/kimi-code.git
cd kimi-code
pnpm install

```

This installs all packages across the monorepo, including the `apps/kimi-code` package that contains the server entry point.

## Starting the Development Server

The primary command to run the kimi-code development server locally is `pnpm dev:server`. This script is defined in [`apps/kimi-code/package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/package.json) and orchestrates the entire startup process.

```bash
pnpm dev:server

```

### What Happens When You Run `pnpm dev:server`

According to the source code in [`apps/kimi-code/package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/package.json), the `dev:server` script executes:

```bash
tsx --tsconfig ./tsconfig.dev.json src/main.ts web --no-open --debug-endpoints

```

This command performs the following actions:

1. **Loads the development configuration** ([`tsconfig.dev.json`](https://github.com/MoonshotAI/kimi-code/blob/main/tsconfig.dev.json)) which enables `experimentalDecorators` for dependency injection and pulls in all workspace package sources
2. **Invokes the entry point** ([`src/main.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/main.ts)) with the `web` sub-command, instructing the server to boot in HTTP/WebSocket mode rather than terminal UI mode
3. **Prevents browser auto-open** (`--no-open`) to avoid interrupting your workflow
4. **Enables debug endpoints** (`--debug-endpoints`) which register diagnostic routes under `/api/v1/debug/*` for inspecting the DI registry and service state

The server listens on **http://127.0.0.1:58627** by default. You can override this by setting the `KIMI_BACKEND_DEFAULT_URL` environment variable before starting the process.

### The Development Wrapper Script

Behind the scenes, `scripts/dev.mjs` serves as the orchestration layer. This Node.js script:

- Spawns the `tsx` process with the appropriate import loader (`../../build/register-raw-text-loader.mjs`) to handle raw text assets during development
- Injects environment variables for the plugin marketplace, starting a local marketplace server unless `KIMI_CODE_DEV_MARKETPLACE_URL` is provided externally
- Handles process cleanup and error propagation

You should see console output indicating the plugin marketplace dev server URL once the startup sequence completes.

## Development Commands and Options

The repository provides several npm scripts for different development scenarios. Each is defined in the root [`package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json) and delegates to specific workspace configurations.

| Command | Purpose | Source Location |
|---------|---------|----------------|
| `pnpm dev:server` | Launches the kap-server with debug endpoints on port 58627 | [`apps/kimi-code/package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/package.json) |
| `pnpm dev:cli` | Runs the Kimi Code CLI in development mode, connecting to the local server | [`apps/kimi-code/package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/package.json) |
| `pnpm dev:web` | Starts the Vite dev server for the web UI (port 5173), proxying `/api/v1` requests to the local kap-server | [`apps/kimi-web/package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-web/package.json) |
| `pnpm dev:v2` | Spawns a second kap-server instance on port 58628 for multi-backend testing | Root [`package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json) |
| `pnpm dev:server:restart` | Watch-mode helper that restarts the server on file changes while preserving the home directory | Root [`package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json) |

### Running the CLI Against Your Local Server

To interact with the agent via terminal while your local server is running:

```bash
pnpm dev:cli

```

This connects the TUI (Terminal User Interface) to the kap-server you started with `pnpm dev:server`, allowing you to test agent behavior against your local modifications.

### Running the Web UI

To develop the React-based frontend while connected to your local backend:

```bash
pnpm dev:web

```

The Vite development server starts on **http://localhost:5173** (or the next available port) and proxies all API requests to `http://127.0.0.1:58627`, enabling full-stack development with hot module replacement.

## Architecture Details

Understanding the server architecture helps troubleshoot startup issues and configure advanced development scenarios.

### Entry Point: [`src/main.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/main.ts)

The central entry point uses **Commander.js** to parse CLI arguments. When invoked with the `web` sub-command, it bypasses the terminal UI (`runShell` from [`src/cli/run-shell.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/cli/run-shell.ts)) and instead initializes the HTTP/WebSocket server. This same entry point handles both headless prompt execution (`runPrompt`) and the development server mode.

### TypeScript Configuration

The [`tsconfig.dev.json`](https://github.com/MoonshotAI/kimi-code/blob/main/tsconfig.dev.json) file extends the base configuration to include all workspace packages in the compilation scope. This is crucial for development because it allows the server to resolve imports from sibling packages (like shared utilities or protocol definitions) without requiring a build step.

### Debug Endpoints

When `--debug-endpoints` is active, the server exposes routes under `/api/v1/debug/*` that provide introspection into the dependency injection container. These endpoints reveal the entire service registry and internal state, making them invaluable for verifying that your changes to service providers or decorators are being registered correctly.

## Configuring Server Ports and URLs

You can customize the development server behavior using environment variables:

- `KIMI_BACKEND_DEFAULT_URL` – Changes the server's listen address and port (default: `http://127.0.0.1:58627`)
- `KIMI_CODE_DEV_MARKETPLACE_URL` – Points to an external plugin marketplace instead of starting the local dev server

Example with custom port:

```bash
KIMI_BACKEND_DEFAULT_URL=http://127.0.0.1:9000 pnpm dev:server

```

## Summary

- **Install Node.js ≥24.15.0 and pnpm 10.33.0** before attempting to run the kimi-code development server locally.
- **Use `pnpm dev:server`** to start the kap-server with debug endpoints enabled on port 58627.
- **The entry point** [`apps/kimi-code/src/main.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/main.ts) receives the `web` argument to boot in server mode rather than TUI mode.
- **Development scripts** in `apps/kimi-code/scripts/dev.mjs` handle environment setup and the optional local plugin marketplace.
- **Access debug routes** at `/api/v1/debug/*` when starting with the `--debug-endpoints` flag to inspect the DI registry.
- **Override default ports** by setting `KIMI_BACKEND_DEFAULT_URL` before running the start command.

## Frequently Asked Questions

### What is the default port for the kimi-code development server?

The kap-server listens on **port 58627** by default when started with `pnpm dev:server`. You can verify this in the console output or by checking the `KIMI_BACKEND_DEFAULT_URL` environment variable, which defaults to `http://127.0.0.1:58627` according to the source configuration.

### How do I enable debug endpoints when running the server?

Debug endpoints are automatically enabled when you use the `pnpm dev:server` command. The npm script passes the `--debug-endpoints` flag to [`src/main.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/main.ts), which registers diagnostic routes under `/api/v1/debug/*`. These routes expose the dependency injection registry and service state for troubleshooting.

### What is the difference between `pnpm dev:server` and `pnpm dev:cli`?

**`pnpm dev:server`** starts the HTTP/WebSocket backend (kap-server) that exposes REST APIs under `/api/v1`, while **`pnpm dev:cli`** launches the Terminal User Interface that connects to an existing server instance. You typically run `dev:server` in one terminal to start the backend, then `dev:cli` in another to interact with it, or use `dev:web` to connect via the browser interface.

### How do I run a second development server instance for testing?

Use **`pnpm dev:v2`** to spawn a secondary kap-server instance on port 58628. This is useful for testing multi-backend scenarios, comparing behavior between different code versions, or developing features that require communication between multiple server instances. The command uses the same `scripts/dev.mjs` wrapper but overrides the port configuration internally.