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

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:

node --version   # → 24.15.x or higher

pnpm --version   # → 10.33.x

Installation and Setup

Clone the repository and install workspace dependencies using pnpm.

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 and orchestrates the entire startup process.

pnpm dev:server

What Happens When You Run pnpm dev:server

According to the source code in apps/kimi-code/package.json, the dev:server script executes:

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) which enables experimentalDecorators for dependency injection and pulls in all workspace package sources
2. Invokes the entry point (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 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
pnpm dev:cli	Runs the Kimi Code CLI in development mode, connecting to the local server	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
pnpm dev:v2	Spawns a second kap-server instance on port 58628 for multi-backend testing	Root package.json
pnpm dev:server:restart	Watch-mode helper that restarts the server on file changes while preserving the home directory	Root package.json

Running the CLI Against Your Local Server

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

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:

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

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) 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 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:

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 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, 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.

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