---
url: /kimi-cli/en/reference/kimi-web.md
---
# Web UI

Web UI provides a browser-based interactive interface, allowing you to use all features of Kimi Code CLI in a web page. Compared to the terminal interface, Web UI offers a richer visual experience, more flexible session management, and more convenient file operations.

## Starting Web UI

Run the `kimi web` command in your terminal to start the Web UI server:

```sh
kimi web
```

After the server starts, it will automatically open your browser to access the Web UI. The default address is `http://127.0.0.1:5494`.

If the default port is occupied, the server will automatically try the next available port (default range `5494`–`5503`) and print the access address in the terminal.

## Command line options

### Network configuration

| Option | Short | Description |
|--------|-------|-------------|
| `--host TEXT` | `-h` | Bind to specific IP address |
| `--network` | `-n` | Enable network access (bind to `0.0.0.0`) |
| `--port INTEGER` | `-p` | Specify port number (default: `5494`) |

By default, Web UI only listens on the local loopback address `127.0.0.1`, allowing access only from the local machine.

If you want to access Web UI from a local network or the public internet, you can use the `--network` option or specify `--host`:

```sh
# Bind to all network interfaces, allowing LAN access
kimi web --network

# Bind to a specific IP address
kimi web --host 192.168.1.100
```

::: warning Note
When enabling network access, be sure to configure access control options (such as `--auth-token` and `--lan-only`) to ensure security. See [Access control](#access-control).
:::

### Browser control

| Option | Description |
|--------|-------------|
| `--open / --no-open` | Automatically open browser on startup (default: `--open`) |

Use `--no-open` to prevent automatically opening the browser:

```sh
kimi web --no-open
```

### Development options

| Option | Description |
|--------|-------------|
| `--reload` | Enable auto-reload (for development) |

Use `--reload` to automatically restart the server after code changes:

```sh
kimi web --reload
```

::: info Note
The `--reload` option is only for development purposes and is not needed for daily use.
:::

### Access control

Web UI provides multi-layer access control mechanisms to ensure service security.

| Option | Description |
|--------|-------------|
| `--auth-token TEXT` | Set Bearer Token for API authentication |
| `--allowed-origins TEXT` | Set allowed Origin list (comma-separated) |
| `--lan-only / --public` | Only allow LAN access (default) or allow public access |
| `--restrict-sensitive-apis / --no-restrict-sensitive-apis` | Restrict sensitive API access (config write, open-in, file access limits) |
| `--dangerously-omit-auth` | Disable authentication checks (dangerous, trusted networks only) |

::: info Added
Access control options added in version 1.6.
:::

#### Access token authentication

Use `--auth-token` to set an access token. Clients need to include `Authorization: Bearer <token>` in the HTTP request header to access the API:

```sh
kimi web --network --auth-token my-secret-token
```

::: tip
The access token should be a randomly generated string with at least 32 characters. You can use `openssl rand -hex 32` to generate a random token.
:::

#### Origin checking

Use `--allowed-origins` to restrict the origin domains that can access Web UI:

```sh
kimi web --network --allowed-origins "https://example.com,https://app.example.com"
```

::: tip
When using `--network` or `--host` to enable network access, it is recommended to configure `--allowed-origins` to prevent Cross-Site Request Forgery (CSRF) attacks.
:::

#### Network access scope

By default, Web UI uses `--lan-only` mode, only allowing access from the local network (private IP address ranges). If you need to allow public access, use the `--public` option:

```sh
kimi web --network --public --auth-token my-secret-token
```

::: danger Warning
Using the `--public` option will allow access from any IP address. Be sure to configure `--auth-token` and `--allowed-origins` to ensure security.
:::

#### Restricting sensitive APIs

Use `--restrict-sensitive-apis` to disable some sensitive API features:

* Config file writing
* Open-in functionality (opening local files, directories, applications)
* File access restrictions

```sh
kimi web --network --restrict-sensitive-apis
```

In `--public` mode, `--restrict-sensitive-apis` is enabled by default; in `--lan-only` mode (default), it is not enabled.

::: tip
When you need to expose Web UI to untrusted network environments, it is recommended to enable the `--restrict-sensitive-apis` option.
:::

#### Disabling authentication (not recommended)

In trusted private network environments, you can use `--dangerously-omit-auth` to skip all authentication checks:

```sh
kimi web --dangerously-omit-auth
```

::: danger Warning
The `--dangerously-omit-auth` option completely disables authentication and access control. It should only be used in fully trusted network environments (such as offline local development environments). Do not use this option on the public internet or untrusted local networks.
:::

## Switching from terminal to Web UI

If you are using Kimi Code CLI in shell mode in the terminal, you can enter the `/web` command to quickly switch to Web UI:

```
/web
```

After execution, Kimi Code CLI will automatically start the Web UI server and open the current session in the browser. You can continue the conversation in Web UI, and the session history will remain synchronized.

## Web UI features

### Session management

Web UI provides a convenient session management interface:

* **Session list**: View all historical sessions, including session title and working directory
* **Session search**: Quickly filter sessions by title or working directory
* **Create session**: Create a new session with a specified working directory; if the specified path doesn't exist, you will be prompted to confirm creating the directory. Supports Cmd/Ctrl+Click on new-session buttons to open session creation in a new tab
* **Switch session**: Switch to different sessions with one click
* **Session fork**: Create a branching session from any assistant response, exploring different directions without affecting the original session
* **Session archive**: Sessions older than 15 days are automatically archived. You can also archive manually. Archived sessions don't appear in the main list but can be unarchived at any time
* **Bulk operations**: Bulk archive, unarchive, or delete sessions in multi-select mode

::: info Added
Session search feature added in version 1.5. Directory auto-creation prompt added in version 1.7. Session fork, archive, and bulk operations added in version 1.9.
:::

### Prompt toolbar

Web UI provides a unified prompt toolbar above the input box, displaying various information in collapsible tabs:

* **Context usage**: Shows the current context usage percentage. Hover to view detailed token usage breakdown (including input/output tokens, cache read/write, etc.)
* **Activity status**: Shows the current agent state (processing, waiting for approval, etc.)
* **Message queue**: Queue follow-up messages while the AI is processing; queued messages are sent automatically when the current response completes
* **File changes**: Detects Git repository status, showing the number of new, modified, and deleted files (including untracked files). Click to view a detailed list of changes
* **Todo list**: When the `SetTodoList` tool is active, shows task progress with support for expanding to view the detailed list
* **Plan mode**: Toggle plan mode on/off from the input toolbar. When plan mode is active, the composer displays a dashed blue border. Plan mode can also be set programmatically via the `set_plan_mode` Wire protocol method

::: info Changed
Git diff status bar added in version 1.5. Activity status indicator added in version 1.9. Version 1.10 unified it into the prompt toolbar. Version 1.11 moved the context usage indicator to the prompt toolbar. Plan mode toggle added in version 1.20.
:::

### Open-in functionality

Web UI supports opening files or directories in local applications:

* **Open in Terminal**: Open directory in terminal
* **Open in VS Code**: Open file or directory in VS Code
* **Open in Cursor**: Open file or directory in Cursor
* **Open in System**: Open with system default application

::: info Added
Open-in functionality added in version 1.5.
:::

::: warning Note
Open-in functionality requires browser support for Custom Protocol Handler. This feature is disabled when using the `--restrict-sensitive-apis` option.
:::

### Slash commands

Web UI supports slash commands. Type `/` in the input box to open the command menu:

* **Autocomplete**: Filter matching commands as you type
* **Keyboard navigation**: Use up/down arrow keys to select commands, Enter to confirm
* **Alias support**: Support command alias matching, e.g., `/h` matches `/help`

### File mentions

Web UI supports file mentions. Type `@` in the input box to open the file mention menu, allowing you to reference files in your conversation:

* **Uploaded attachments**: Mention files attached to the current message
* **Workspace files**: Mention existing files in the current session's working directory
* **Autocomplete**: Filter matching files by name or path as you type
* **Keyboard navigation**: Use up/down arrow keys to select files, Enter or Tab to confirm, Escape to cancel

### Message actions

Assistant messages provide the following action buttons:

* **Copy**: Copy message content to clipboard with one click
* **Fork**: Create a branching session from the current response

::: info Added
Copy and fork buttons added in version 1.10.
:::

### Structured questions

When the AI uses the `AskUserQuestion` tool, Web UI displays a structured question dialog in the chat area, replacing the input box at the bottom. The question dialog shows the question description and available options, supporting single-select, multi-select, and custom text input. When the AI asks multiple questions at once, the dialog shows a tab bar at the top listing all questions, with support for click navigation, keyboard navigation, and restoring previous selections when revisiting answered questions. After answering all questions, the dialog closes automatically and the AI continues execution based on your choices.

::: info Added
Structured questions added in version 1.14.
:::

### Approval keyboard shortcuts

When the agent sends an approval request, you can use keyboard shortcuts to respond quickly:

| Shortcut | Action |
|----------|--------|
| `1` | Approve |
| `2` | Approve for session |
| `3` | Decline |
| `4` | Decline with feedback |

Press `4` to enter feedback mode, where you can type a reason for declining or instructions on how the agent should adjust, then press Enter to submit. The feedback text is passed to the agent to guide its next attempt.

When an approval request originates from a subagent, the dialog shows a source label (e.g. "coder agent") so you know which agent initiated the request.

::: info Added
Approval keyboard shortcuts added in version 1.10. Feedback mode added in version 1.25.
:::

### Tool output

Web UI provides rich display for tool call output:

* **Media preview**: Images and videos read by the `ReadMediaFile` tool are displayed as clickable thumbnails

* **Shell commands**: `Shell` tool commands and output are rendered with dedicated components

* **Todo list**: `SetTodoList` tool items are displayed as a structured list

* **Tool input parameters**: Redesigned tool input UI with expandable parameter details and syntax highlighting for long values

* **Context compaction**: A compaction indicator is shown when context compaction is in progress

* **Quick URL open**: The URL parameter of the `FetchURL` tool supports Cmd/Ctrl+Click to open the link in a new tab

* **Subagent origin indicators**: Tool calls originating from a subagent are rendered with a left border and a source type label (e.g. "coder agent") for clearer attribution; subagent activity panels display the specific agent type (e.g. "Coder agent working") instead of a generic label

::: info Added
Media preview, shell command, and todo list display components added in version 1.9. Quick URL open added in version 1.14. Subagent origin indicators added in version 1.25.
:::

### Rich media support

Web UI supports viewing and pasting various types of rich media content:

* **Images**: Display images directly in the chat interface
* **Code highlighting**: Automatic code block recognition and highlighting
* **Markdown rendering**: Support for full Markdown syntax

### Responsive layout

Web UI uses responsive design and displays well on screens of different sizes:

* Desktop: Sidebar + main content area layout
* Mobile: Collapsible drawer-style sidebar

::: info Changed
Responsive layout improved in version 1.6 with enhanced hover effects and better layout handling.
:::

### URL action parameters

Web UI supports URL parameters to trigger specific actions, making it easy to integrate from external tools or scripts:

| Parameter | Description |
|-----------|-------------|
| `?action=create` | Open the create-session dialog |
| `?action=create-in-dir&workDir=<path>` | Directly create a session in the specified working directory |

Examples:

```
http://127.0.0.1:5494?action=create
http://127.0.0.1:5494?action=create-in-dir&workDir=/path/to/project
```

## Examples

### Local use

The simplest usage, accessible only from the local machine:

```sh
kimi web
```

### LAN sharing

Share Web UI on the local network with access token protection:

```sh
kimi web --network --auth-token $(openssl rand -hex 32)
```

After execution, the terminal will display the access address and token. Other devices can access through that address and enter the token in the browser for authentication.

### Public access

Deploy Web UI in a public internet environment (requires careful security configuration):

```sh
kimi web \
  --host 0.0.0.0 \
  --public \
  --auth-token $(openssl rand -hex 32) \
  --allowed-origins "https://yourdomain.com" \
  --restrict-sensitive-apis
```

### Development

Enable auto-reload for development purposes:

```sh
kimi web --reload --no-open
```

## Technical details

Web UI is built on the following technologies:

* **Backend**: FastAPI + WebSocket
* **Frontend**: React + TypeScript + Vite
* **API protocol**: Complies with OpenAPI specification, see `web/openapi.json`

Web UI communicates with Kimi Code CLI's Wire mode via WebSocket, enabling real-time bidirectional data transmission.