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

> Run Kimi-Code locally with our setup guide. Install Nodejs and pnpm, clone the repo, and launch the backend server and terminal UI for effortless local development.

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

---

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

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

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

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

```bash
pnpm dev:v1

```

This command executes two processes:
1. Starts the **kap-server** from [`packages/kap-server/src/start.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/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:

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

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

```bash
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`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json)
- **Monorepo structure**: Workspace defined by [`pnpm-workspace.yaml`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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.