How to Use the Vis Server Component in kimi-code: A Complete Setup Guide

The Vis server in kimi-code is a Hono-based HTTP service that visualizes sessions, tasks, logs, and sub-agents through an interactive web UI, started either programmatically via startVisServer() or through the built-in CLI.

The Vis server component in MoonshotAI/kimi-code provides a self-contained visualization layer for Kimi Code operations. Located at apps/vis/server, it transforms raw session data into an explorable web interface. This guide covers the architecture, configuration options, and practical steps to run the server in your own environment.

---

Core Architecture of the Vis Server

The Vis server follows a layered design built on the Hono framework with clear separation between bootstrap logic, configuration, routing, and domain utilities.

Layer	Purpose	Key Source File
Server bootstrap	Creates the Hono app, injects auth token and home directory, launches Node HTTP server	[apps/vis/server/src/start.ts](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vis/server/src/start.ts)
Configuration helpers	Resolves host, port, auth token, and asset location from environment or defaults	[apps/vis/server/src/config.ts](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vis/server/src/config.ts)
Route handlers	Exposes REST endpoints for sessions, wires, tasks, logs, imports, cron jobs, and context	[apps/vis/server/src/routes/sessions.ts](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vis/server/src/routes/sessions.ts), [apps/vis/server/src/routes/wire.ts](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vis/server/src/routes/wire.ts)
Domain libraries	Parses JSON-L wire format, stores tasks, resolves blobs	[apps/vis/server/src/lib/wire-reader.ts](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vis/server/src/lib/wire-reader.ts)
Web assets	Compiled React UI served by the server (or custom builds)	apps/vis/web/*

The server uses @hono/node-server's serve helper to bind hostname, port, and the request handler (app.fetch). The Vis UI communicates via the same REST API that the @moonshot-ai/kimi-code-sdk CLI uses.

---

Starting the Vis Server

You have two primary methods to start the Vis server: programmatically from your Node.js code or through the package CLI.

Programmatic Start with startVisServer()

Import startVisServer from the server entry point and pass an options object to override defaults:

import { startVisServer } from '@moonshot-ai/kimi-code/apps/vis/server/src/start';

const opts = {
  // Directory where Kimi Code stores sessions
  // Default: $KIMI_CODE_HOME or ~/.kimi-code
  homeDir: '/home/user/.kimi-code',
  
  // Port 0 auto-selects a free port; specify a number for fixed port
  port: 3002,
  
  // Host name binding
  // Default: $KIMI_VIS_HOST or "localhost"
  host: '127.0.0.1',
  
  // Bearer token for UI authentication
  // Default: $KIMI_VIS_AUTH_TOKEN
  authToken: 'example-token',
};

async function run() {
  const server = await startVisServer(opts);
  console.log(`Vis UI → ${server.url}`);
  
  // Graceful shutdown when needed
  // await server.close();
}

run().catch(console.error);

The startVisServer function in [start.ts](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vis/server/src/start.ts) returns a StartedVisServer object containing:

• port — resolved port number
• host — bound hostname
• url — full URL for browser access
• close() — async method to stop the server

CLI Start Method

The repository provides a convenience script that wraps the same bootstrap logic:

# Using pnpm filter

pnpm --filter @moonshot-ai/kimi-code-vis-server run start

# Or the shorthand script

pnpm run vis

Both commands invoke startVisServer() internally and respect the same environment variables.

---

Configuration Options

Configuration resolution happens in [apps/vis/server/src/config.ts](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vis/server/src/config.ts). The following environment variables control runtime behavior:

Variable	Description	Default
KIMI_CODE_HOME	Root directory for all session data	~/.kimi-code
PORT	TCP port for the Vis server (0 = auto-select)	3001
KIMI_VIS_HOST	Hostname the server binds to	localhost
KIMI_VIS_AUTH_TOKEN	Bearer token required by the UI	Randomly generated on first start if omitted
KIMI_WEB_ASSET	Path or URL to custom UI bundle	apps/vis/web/dist (pre-built bundle)

Pass these as environment variables or override them programmatically through the opts parameter of startVisServer().

---

Accessing and Using the Vis UI

Once started, open the printed URL (e.g., http://localhost:3002/) in a browser. The interface presents:

• Session list — tabular view of all recorded sessions
• Session detail — timeline, wire view, tasks, logs, and sub-agent hierarchy
• Task & Cron panels — visualization of scheduled job execution
• Context view — inspection of the agent's internal context projection

The UI authenticates using the configured authToken (if set) before granting access.

---

Practical Code Examples

Embedding Vis in a Custom Tool

Integrate the server into your own workflow to launch visualization alongside SDK operations:

import { startVisServer } from '@moonshot-ai/kimi-code/apps/vis/server/src/start';
import { fetchSessionInfo } from '@moonshot-ai/kimi-code-sdk';

(async () => {
  const { url, close } = await startVisServer({ port: 0 });
  console.log(`Vis UI running at ${url}`);

  const session = await fetchSessionInfo({ sessionId: 'abc123' });
  console.log('Session state:', session.state);

  process.once('SIGINT', async () => {
    await close();
    console.log('Vis server stopped.');
  });
})();

Using a Custom UI Bundle

Replace the default React bundle with your own build:

import { startVisServer } from '@moonshot-ai/kimi-code/apps/vis/server/src/start';
import { readFileSync } from 'fs';

const customAsset = {
  indexHtml: readFileSync('my-custom-dist/index.html', 'utf-8'),
  bundleJs: readFileSync('my-custom-dist/bundle.js', 'utf-8'),
};

await startVisServer({ webAsset: customAsset });

Alternatively, set KIMI_WEB_ASSET to a directory path or URL pointing to your custom build.

---

Key Source Files Reference

Path	Role
apps/vis/server/src/start.ts	Entry point: creates Hono app and starts HTTP server
apps/vis/server/src/config.ts	Resolves runtime configuration from environment/defaults
apps/vis/server/src/routes/*.ts	REST endpoints: sessions, wire, tasks, logs, imports, cron, context, blobs
apps/vis/server/src/lib/wire-reader.ts	Parses wire JSON-L format for timeline rendering
apps/vis/server/src/lib/zip-import.ts	Handles ZIP-based session imports
apps/vis/web/*	Pre-built React frontend bundle
apps/vis/server/package.json	Dependencies and npm scripts

---

Summary

• Import startVisServer from @moonshot-ai/kimi-code/apps/vis/server/src/start to launch the Vis server programmatically
• Set environment variables (KIMI_CODE_HOME, PORT, KIMI_VIS_HOST, KIMI_VIS_AUTH_TOKEN) to configure without code changes
• Use port 0 for automatic free port selection in dynamic environments
• Replace webAsset to serve custom React builds through the same server infrastructure
• Access the UI at the printed URL to explore sessions, wires, tasks, and logs visually

The Vis server component is fully TypeScript-typed and designed for embedding into any Kimi Code workflow.

---

Frequently Asked Questions

What is the default port for the kimi-code Vis server?

The default port is 3001, defined in [apps/vis/server/src/config.ts](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vis/server/src/config.ts). You can override this via the PORT environment variable or the port option in startVisServer(). Setting port: 0 triggers automatic port selection.

How do I secure the Vis server with authentication?

Set the KIMI_VIS_AUTH_TOKEN environment variable or pass authToken to startVisServer(). The UI will prompt for this bearer token on first access. If no token is configured, the server generates a random token on startup and prints it to the console.

Can I run the Vis server without the rest of kimi-code?

Yes. The Vis server at apps/vis/server is self-contained. It only requires a valid KIMI_CODE_HOME directory containing session data. The server reads this data directly without needing the full Kimi Code CLI or SDK running concurrently.

How do I customize the web UI that the Vis server serves?

Build your custom React bundle and point the server to it using either the KIMI_WEB_ASSET environment variable or the webAsset option in startVisServer(). The expected format is an object with indexHtml and bundleJs string properties, or a path to a directory containing these files.

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