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

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 – 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 – Creates the InspectClient that communicates with the Kap Server over REST and WebSocket protocols, handling base URL injection and optional authentication tokens.
• 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.

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:

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:

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

pnpm dev:inspect

This command executes the Vite configuration defined in 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) 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 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.
• Transcript data – Fetched through the REST helpers in 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 and merged into the Redux-style store at 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 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, while the React entry point is 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 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. 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.

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