# How to Set Up the Kimi-Inspect Web Debugger: Complete Configuration Guide

> Learn how to set up the Kimi-Inspect web debugger with this complete configuration guide. Follow simple steps to connect the UI to your Kap Server and start debugging.

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

---

**The Kimi-Inspect web debugger is a Vite-powered React UI that connects to a running Kap Server, requiring you to start the backend with `pnpm dev:v1` or `pnpm dev:v2`, then launch the UI with `pnpm dev:inspect` to access the debugging interface at `http://localhost:5176`.**

The **kimi-inspect web debugger** provides a browser-based interface for inspecting live sessions, agents, and model states within the MoonshotAI/kimi-code ecosystem. This lightweight React application connects to the Kap Server backend through an intelligent proxy configuration that eliminates CORS issues while delivering real-time WebSocket updates for active debugging sessions.

## Architecture Overview

The debugger consists of three integrated components that work together to provide seamless debugging capabilities:

- **[`vite.config.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/vite.config.ts)** – Defines the development server, proxy rules to the Kap Server, and the **server-discovery plugin** that automatically locates running server instances on the host.
- **[`connection.tsx`](https://github.com/MoonshotAI/kimi-code/blob/main/connection.tsx)** – Creates the `InspectClient` that communicates with the Kap Server over REST and WebSocket protocols, handling base URL injection and optional authentication tokens.
- **[`ServerSwitcher.tsx`](https://github.com/MoonshotAI/kimi-code/blob/main/ServerSwitcher.tsx)** – Provides the UI control for selecting a server URL manually or relying on auto-discovered instances, located at [`apps/kimi-inspect/src/components/ServerSwitcher.tsx`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-inspect/src/components/ServerSwitcher.tsx).

## Step-by-Step Setup Instructions

Follow these steps to get the debugger running locally.

### 1. Clone and Install Dependencies

Start by cloning the repository and installing the required packages:

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

```

### 2. Start the Kap Server Backend

The debugger requires a running Kap Server (the backend providing the `/api/v1` RPC surface). Start it using one of the following commands:

```bash

# Option A: Start the V1 backend

pnpm dev:v1

# Option B: Start the V2 backend

pnpm dev:v2

```

By default, the server listens on `http://127.0.0.1:58627`. The development scripts automatically include the `--debug-endpoints` flag required to expose the debug routes.

### 3. Launch the Kimi-Inspect Dev Server

With the backend running, start the debugger UI:

```bash
pnpm dev:inspect

```

This command executes the Vite configuration defined in [`apps/kimi-inspect/vite.config.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-inspect/vite.config.ts), which launches the development server on **port 5176** (unless overridden). The configuration automatically proxies any request under `/api/**` to the Kap Server, avoiding cross-origin issues by presenting a unified origin to the browser.

### 4. Access the Debugger Interface

Open your browser and navigate to:

```

http://localhost:5176

```

The UI will attempt to auto-connect to the Kap Server discovered by the server-discovery plugin. If auto-discovery fails or you need to connect to a different instance, use the **Server Switcher** control in the top-right corner to enter the full URL (e.g., `http://127.0.0.1:58627`).

## Environment Configuration

You can customize the debugger behavior using environment variables. Create a `.env` file at the repository root or export these variables in your shell:

| Variable | Description | Default Value |
|----------|-------------|---------------|
| `INSPECT_PORT` | Port for the Vite development server | `5176` |
| `KIMI_SERVER_URL` | Base URL of the Kap Server for API proxying | `http://127.0.0.1:58627` |
| `INSPECT_PREVIEW_PORT` | Port for `vite preview` (static build preview) | `4176` |

Vite automatically picks up these values and injects `__KIMI_INSPECT_PROXY_TARGET__` with the `KIMI_SERVER_URL` value during the build process.

## How the Connection Layer Works

Understanding the internal wiring helps troubleshoot connection issues.

### Server Discovery Mechanism

The **server-discovery plugin** (implemented in [`apps/kimi-inspect/vite/serverDiscovery.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-inspect/vite/serverDiscovery.ts)) scans the `~/.kimi-code/server/instances` directory on startup. It detects locally-running Kap Server entries and populates the dropdown list used by the `ServerSwitcher` component, allowing quick switching between multiple backend instances without manual URL entry.

### Client Initialization

When the UI mounts, [`apps/kimi-inspect/src/connection.tsx`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-inspect/src/connection.tsx) instantiates an `InspectClient` that wraps the `@moonshot-ai/klient` SDK. This client becomes the single source of truth for all data fetching:

- **Workspace and session lists** – Retrieved via `klient.core(IWorkspaceService).list()` as implemented in [`apps/kimi-inspect/src/components/Sidebar.tsx`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-inspect/src/components/Sidebar.tsx).
- **Transcript data** – Fetched through the REST helpers in [`apps/kimi-inspect/src/transcript/api.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-inspect/src/transcript/api.ts).
- **Real-time updates** – Delivered via the WebSocket-like transport wrapper in [`apps/kimi-inspect/src/channel/wsLike.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-inspect/src/channel/wsLike.ts) and merged into the Redux-style store at [`apps/kimi-inspect/src/transcript/store.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-inspect/src/transcript/store.ts).

### Runtime Server Switching

If you need to switch servers after the UI has loaded, the `ServerSwitcher` component calls `useConnection().setBaseUrl(newUrl)`, which updates the underlying `InspectClient` and triggers a complete data refresh across all components.

## Summary

- The **kimi-inspect web debugger** requires a Kap Server running with `--debug-endpoints` (enabled by default in `pnpm dev:v1` or `pnpm dev:v2`).
- Launch the UI with `pnpm dev:inspect`, which runs the Vite server defined in [`apps/kimi-inspect/vite.config.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-inspect/vite.config.ts) on port 5176 by default.
- The Vite configuration proxies `/api/**` requests to the Kap Server, eliminating CORS restrictions during local development.
- Auto-discovery scans `~/.kimi-code/server/instances` to populate the server selector, but manual URL entry via `ServerSwitcher` is always available.
- Core connection logic resides in [`apps/kimi-inspect/src/connection.tsx`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-inspect/src/connection.tsx), while the React entry point is [`apps/kimi-inspect/src/main.tsx`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-inspect/src/main.tsx).

## Frequently Asked Questions

### What is the default port for the kimi-inspect web debugger?

The Vite development server listens on **port 5176** by default. You can override this by setting the `INSPECT_PORT` environment variable before running `pnpm dev:inspect`.

### How does the debugger automatically find the Kap Server?

The **server-discovery plugin** in [`apps/kimi-inspect/vite/serverDiscovery.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-inspect/vite/serverDiscovery.ts) scans the `~/.kimi-code/server/instances` directory for JSON files describing active server processes. It exposes these entries to the UI, allowing the `ServerSwitcher` component to present them as quick-connect options.

### Can I connect the debugger to a remote Kap Server?

Yes. While the default configuration targets `http://127.0.0.1:58627`, you can either set the `KIMI_SERVER_URL` environment variable before starting the debugger, or use the **Server Switcher** UI component at runtime to point to any accessible URL (e.g., `http://remote-host:58627`).

### Why are my API requests failing with CORS errors?

The **kimi-inspect** setup avoids CORS issues by using Vite's proxy configuration in [`vite.config.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/vite.config.ts). All browser requests to `/api/**` are proxied to the Kap Server, making them same-origin from the browser's perspective. If you see CORS errors, verify that the `KIMI_SERVER_URL` proxy target is correctly set and that the Kap Server is actually running.