How to Run Kimi-Code on a Local Machine: Complete Setup Guide

To run Kimi-Code locally, install Node.js ≥24.15.0 and pnpm 10.33.0, clone the MoonshotAI/kimi-code repository, run pnpm install, then execute pnpm dev:v1 to start the backend server and terminal UI.

Kimi-Code is a TypeScript monorepo developed by MoonshotAI that provides a full-stack development environment for the Kimi AI platform. Learning how to run kimi-code on a local machine requires setting up the dependency-injection based backend, choosing your preferred interface, and ensuring strict adherence to the Node.js version constraints defined in the repository configuration.

Prerequisites

Before you can run kimi-code on a local machine, verify your system meets the requirements enforced by the root package.json and .npmrc files:

• Node.js version 24.15.0 or higher (enforced by engine-strict=true in .npmrc)
• pnpm version 10.33.0 (specified in the engines field)

Use a Node version manager to install the correct runtime:

nvm install 24.15.0
nvm use 24.15.0
corepack enable

Repository Structure Overview

Kimi-Code organizes its codebase as a pnpm monorepo defined by pnpm-workspace.yaml. The architecture separates concerns into distinct packages under packages/* and apps/*:

• packages/kap-server – The core backend server entry point at src/start.ts that boots the DI-based agent engine
• apps/kimi-code – Terminal UI (TUI) application consuming the @moonshot-ai/kimi-code-sdk
• apps/kimi-web – Vue 3 web interface built with Vite
• packages/node-sdk – Public SDK used by both UI applications

Step-by-Step Installation

Clone the Repository

git clone https://github.com/MoonshotAI/kimi-code.git
cd kimi-code

Install Workspace Dependencies

Run pnpm install from the repository root. This resolves all packages according to the workspace configuration:

pnpm install

Running the Development Environment

The repository provides two primary development modes depending on which interface you prefer. Both modes start the kap-server backend but bundle different frontend clients.

Option 1: Terminal UI (TUI)

The terminal UI resides in apps/kimi-code and connects to the backend via the KIMI_SERVER_URL environment variable (defaults to http://127.0.0.1:58627).

Run the convenience script:

pnpm dev:v1

This command executes two processes:

1. Starts the kap-server from packages/kap-server/src/start.ts, which registers REST and WebSocket endpoints under /api/v1 on port 58627
2. Launches the TUI client that automatically connects to the local server instance

Option 2: Web UI

For browser-based interaction, use the Vue 3 application in apps/kimi-web. The Vite development server proxies /api requests to the backend.

Run:

pnpm dev:v2

This starts:

• The backend server (v2 API) on port 58627
• The Vite dev server at http://localhost:5173

Both interfaces interact with the same agent sessions and transcript data stored in the backend.

Backend Server Configuration

The core server implementation lives in packages/kap-server/src/start.ts. This entry point initializes the dependency-injection container, registers API routes, and optionally enables debug endpoints when passed the --debug-endpoints flag.

To start the server independently without launching a UI:

pnpm --filter kap-server start

# Or with debug endpoints enabled

pnpm --filter kap-server start --debug-endpoints

Verifying Your Setup

Run the workspace test suite to ensure all packages function correctly:

pnpm test

This executes tests across all monorepo packages, validating the SDK, server logic, and UI components.

Summary

• System requirements: Node.js ≥24.15.0 and pnpm 10.33.0 are mandatory, enforced by .npmrc and package.json
• Monorepo structure: Workspace defined by pnpm-workspace.yaml with packages in packages/ and apps in apps/
• Quick start: Use pnpm dev:v1 to run both the backend server (packages/kap-server/src/start.ts) and terminal UI
• Alternative interface: Use pnpm dev:v2 to run the backend with the Vue 3 web UI at localhost:5173
• Default endpoint: The server exposes API v1 on http://127.0.0.1:58627 unless overridden by KIMI_SERVER_URL

Frequently Asked Questions

What Node.js version is required to run Kimi-Code locally?

The repository requires Node.js version 24.15.0 or higher. This requirement is strictly enforced by the engine-strict=true setting in the .npmrc file and the engines field in the root package.json. Using an older version will cause installation or runtime errors when resolving workspace dependencies.

How do I switch between the terminal UI and web UI?

Use pnpm dev:v1 to launch the backend server alongside the terminal UI (apps/kimi-code), or use pnpm dev:v2 to start the backend with the Vue 3 web interface (apps/kimi-web). Both commands start the same kap-server instance from packages/kap-server/src/start.ts but bundle different frontend clients. You can also set the KIMI_SERVER_URL environment variable to point the TUI to a different server instance.

Where is the backend server entry point located?

The backend server entry point is packages/kap-server/src/start.ts. This TypeScript file bootstraps the DI-based agent engine, registers REST and WebSocket handlers under /api/v1, and handles server lifecycle management including optional debug routes. You can start it independently using pnpm --filter kap-server start.

Can I run the backend and UI separately?

Yes. While convenience scripts like pnpm dev:v1 start both processes, you can run them independently. Start the server first with pnpm --filter kap-server start, then set the KIMI_SERVER_URL environment variable in your terminal or .env file to point to http://127.0.0.1:58627 before launching the UI application separately from its respective apps/ directory.

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