Kimi Code 2.5 Guide: Remote Environments and Forks

Q: Do --environment flags work when resuming a session?

Both --environment and --environment-cwd are creation-only and cannot be combined with --session or --continue. Resuming a session restores its remote environment and working directory automatically, so you do not need to repeat the flags.

Kimi Code CLI 2.5.0 (November 4, 2026) and patch 2.5.1 (November 5) let you bind a session to an SSH, Docker, or custom-command remote environment so File and Shell tools run on the target while model calls and credentials stay local. You can also fork sessions and switch /model or /effort mid-run.

Last updated: November 5, 2026

What is new in 2.5
Feature comparison
How to set up a remote environment
Forking sessions and mid-run model switches
Limits and plan notes
FAQ
Sources

What is new in Kimi Code 2.5

Moonshot AI shipped Kimi Code CLI 2.5.0 on November 4, 2026 (UTC), then 2.5.1 on November 5, 2026. The official What’s New page and CLI changelog list the same headline features for the coding agent product used from the terminal, web UI, and desktop.

The standout change is remote environments. You declare an SSH host, Docker container, or custom launcher in config.toml, then start a session with kimi --environment <name>. File reads, edits, writes, search, and Shell commands execute on that target. Model requests and API credentials never leave your machine.

Two workflow features arrive in the same release. You can fork from a historical turn or from a still-running session, and you can change /model or /effort while the Agent is busy. Multi-directory projects also merge Skills from every source directory, with the primary directory winning name conflicts.

If you already follow the model line, see our earlier guide to Kimi K3.1 Pro pricing and Highspeed setup. Kimi Code 2.5 is the client/runtime release; K3.1 Pro is the model tier that can run inside it.

Feature comparison

Capability	Before 2.5	Kimi Code 2.5.0 / 2.5.1
Remote SSH / Docker / custom tool host	Not as a creation-time environment binding	Declare `[environments.*]`; bind with `--environment`
Where File / Shell run	Local machine (or prior remote-control flows)	On the bound remote; no silent local fallback on disconnect
Where model calls and credentials run	Local	Still local on your machine
Session fork	Earlier fork tooling with more limits	Fork from a historical turn or while the source session is running
Mid-run `/model` and `/effort`	Switching while busy was restricted	Allowed; applies from the next turn
Multi-directory Skills	Primary workspace skills	Skills merged from every configured directory
Global full-text search index	Built by default in earlier 0.x / 2.x builds	Off by default; set `[database] global_search = true` to re-enable

How to set up a remote environment

The steps below follow Moonshot’s remote environments guide. Confirm each official page returns HTTP 200 before you rely on a link in production docs.

Prepare the remote host. Install the Kimi Code executor for the target platform at ~/.kimi-code/bin/kimi (or kimi.exe on Windows). Kimi Code does not install the executor automatically. Make sure SSH key login works from your machine.
Declare the environment in local config.toml. Example SSH block from the docs:
```
[environments.dev-box]
type = "ssh"
host = "dev-box"
defaultCwd = "/home/me/projects"
```
For Docker, set type = "docker" and container = "myapp-dev". For a custom launcher, use command and args instead of type.
Create the remote session. Run kimi --environment dev-box. Optionally add --environment-cwd /home/me/another-project. Both flags are creation-only and cannot be combined with --session or --continue.
Confirm the split of work. File and Shell tools should show the remote working directory in the welcome panel and Git status in the footer when applicable. Subagents inherit the parent Agent’s remote environment.
Handle auth and disconnects. Prefer keys and ssh-agent. Interactive password prompts need OpenSSH 8.4 or later; kimi -p never prompts for passwords. On disconnect, the next tool call tries to reconnect; an in-flight call fails and is not retried automatically.

Windows remotes are supported over SSH or custom commands (not Docker containers). Use a native path such as C:\work\project for defaultCwd, and install Git for Windows plus the Windows executor.

For other CLI agents with remote or cloud steering, compare Cursor Remote Control on iOS and Antigravity CLI 1.5 remote agents.

Forking sessions and mid-run model switches

Forking. Choose “Fork from here” under a completed historical turn to keep only that turn and earlier content in the new session. You can also fork while the source session is still running and retain the current user prompt. The What’s New notes for Desktop/Web v1.3.0 (same day) describe the same fork behavior for the graphical clients.

Mid-run switches. Use /model and /effort while the Agent is working. A turn that has already started calling the model keeps its settings. The switch applies from the next turn. If you pick Compact and continue, compaction runs after the current turn ends.

These controls matter when you start on a fast coding model and later need a higher-effort reasoning pass without abandoning the remote environment or the conversation history. For competitor CLI churn in the same week, see Claude Code 2.1.318 and Codex CLI 0.166.

Limits and plan notes

Official remote limitations include:

WebSearch and FetchURL always run from your machine.
Hooks and stdio MCP servers without environment_id run on your machine by default.
Remote sessions do not load project-level Agent files from the target.
Remote AGENTS.md and project Skills do not hot reload; they refresh on create/resume or /reload.
File paths in prompts resolve on the target; local paths cannot be read directly (pasted images are unaffected).
Tower mode is unavailable in remote workspaces.
Listing a remote directory with more than 50,000 entries fails.

Membership and model access for K3.1 Pro remain as stated in the October 23, 2026 model rollout: K3.1 Pro on Plus / Moderato and above, with Pro / Allegretto unlocking up to 1M context; K3.1 Pro Highspeed on Pro / Allegretto and above. Thinking stays required for K3.1 Pro models (low / high / max, default high). Those plan details come from the model announcement, not from the 2.5 CLI notes.

Global full-text search is off by default in 2.5.0. Set [database] global_search = true or KIMI_CODE_GLOBAL_SEARCH=1 if you need the prior index behavior.

FAQ

What is new in Kimi Code 2.5?

Version 2.5.0 adds creation-time SSH, Docker, and custom-command remote environments; session forking from a historical turn or a running session; mid-run /model and /effort switches; and merged Skills across multi-directory projects. Version 2.5.1 is a bug-fix release dated November 5, 2026.

How do remote environments keep credentials safe?

According to the official remote environments guide, File and Shell tools run on the remote machine or container, while the CLI, model requests, credentials, and session state stay on your machine. There is no silent fallback to the local machine if the remote disconnects.

Can I change the model while the Agent is working?

Yes. In 2.5.0 you can run /model and /effort while the Agent is working. A turn that has already started keeps its settings; the new settings apply from the next turn. Choosing Compact and continue runs after the current turn ends.

Do –environment flags work when resuming a session?

Both –environment and –environment-cwd are creation-only and cannot be combined with –session or –continue. Resuming a session restores its remote environment and working directory automatically, so you do not need to repeat the flags.

What are the main remote-environment limits?

WebSearch and FetchURL always run from your machine. Hooks and stdio MCP servers without environment_id run locally by default. Remote sessions do not load project-level Agent files from the target, Tower mode is unavailable in remote workspaces, and listing a remote directory with more than 50,000 entries fails.

How does Kimi Code 2.5 relate to Kimi K3.1 Pro?

K3.1 Pro is the model series rolled out in Kimi Code on October 23, 2026. Kimi Code 2.5 is the CLI and product release that adds remote environments and session tooling. Use them together when you want the K3.1 Pro model running tools on a remote box.

Sources

Featured image: CSS code on a screen, Wikimedia Commons (Unsplash), CC0 public domain.

Kimi Code 2.5: Power-User Guide to Remote Environments

Table of contents