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

> Learn to use the Vis server component in kimi-code with our complete setup guide. Visualize sessions, tasks, logs, and sub-agents easily via web UI or CLI. Get started today!

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

---

**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)](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)](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)](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)](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)](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:

```typescript
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/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:

```bash

# 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)](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:

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

```typescript
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`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vis/server/src/start.ts) | Entry point: creates Hono app and starts HTTP server |
| [`apps/vis/server/src/config.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vis/server/src/lib/wire-reader.ts) | Parses wire JSON-L format for timeline rendering |
| [`apps/vis/server/src/lib/zip-import.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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)](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.