Subagents and Hotcell sandboxes

#What subagents are

A subagent is a separate, read-only Autopilot instance that runs in a local Hotcell sandbox. The main agent (the coordinator) keeps the conversation, hands independent investigations to subagents, waits for their cited findings, and makes any edits itself in your checkout.

There is no remote worker mode. Subagents always run locally through Hotcell.

You don't need to ask for subagents. On substantial tasks the coordinator decides whether delegation is worth it. Say "don't use subagents" to opt out for a request, or "use subagents" to insist. An explicit request always wins over the policy.

#Requirements

• Hotcell installed and its daemon running on this machine.

• Your OpenRouter key added to Hotcell's host key store, on the daemon host:

  hotcell keys add openrouter
  

• OpenRouter as the active provider (/provider openrouter). Hotcell's egress gateway only speaks OpenRouter, so subagents are unavailable while another provider is active.

• A Git repository as the working directory.

The real key never enters a sandbox. The Hotcell daemon owns provider credentials and injects its own gateway token; Autopilot does not pass its OpenRouter key to the sandbox.

#What a subagent sees

Autopilot packs your current working tree and streams it into the sandbox: tracked files with your edits, plus untracked files that aren't gitignored. Private repositories work, nothing needs to be pushed, and no GitHub credentials are involved. The subagent sees files, not Git history.

Secrets are never copied, even if tracked: .env*, *.pem, *.key, id_rsa*, .npmrc, .netrc and similar.

If the packed tree is larger than 24 MB compressed, the sandbox clones origin instead and applies your local changes as a patch. That path needs a credential-free HTTPS or SSH URL the daemon can clone, so a public repository. KIMIFLARE_WORKER_ARCHIVE=0 forces the clone path.

#What a subagent can do

Subagents are research-only. They cannot edit files, run a shell, open pull requests or use MCP tools. Each one has a narrow read-only tool profile, a wall-clock timeout, a concurrency limit and a cleanup lifecycle.

A subagent ends with a JSON report of cited findings, open questions and files read, which the coordinator receives as structured results. An answer without a valid report is passed through and marked unverified.

#First run

The first subagent after an install builds a cached runtime: the Autopilot CLI matching your version (autopilot-ai@<version>) is installed once in a scratch sandbox, which takes about two minutes, and saved as a Hotcell backup. Later subagents restore it in about a second.

Your project's own dependencies and install scripts are never run.

#Delegation policy

Set the policy with /subagents auto|suggest|off, the subagentPolicy config key, or KIMIFLARE_SUBAGENT_POLICY.

The harness never starts a subagent by itself. The agent calls the subagent tool, which always needs normal tool permission. When several subagents launch in one step they run in parallel, and one prompt listing every mission approves or denies the whole batch.

On OpenRouter, Jev (a fast yes/no decision model) refines the policy. In auto it checks whether a substantial request has independent parts; in suggest it decides whether to suggest at all. It receives at most 1,200 characters of redacted request text, and any failure falls back to the default guidance.

#Watch and stop subagents

These commands run immediately, even while the agent is busy. Interrupting a turn with Ctrl+C is separate and stops everything in that turn.

#Background subagents

The subagent tool takes background: true. The call returns a worker id at once and the agent keeps working, or answers you, while the subagent runs. When it finishes, its findings are delivered to the agent automatically: at the next tool step if a turn is running, or with your next message. The agent can also check early with worker_status, fetch a result with worker_result (optionally wait=true), or call wait_for with worker_id.

Background subagents keep every safeguard: the same permission prompt, timeout, concurrency limit and read-only profile. They are not tied to a turn, so interrupting a turn doesn't stop them. Stop one with /subagents cancel <n>. They live as long as the Autopilot session. In the SDK, a finished one emits worker.finished, and disposing a session cancels its running background subagents.

#Limits and cost

Other environment variables:

Subagents add model cost and latency. Actual cost is read from Hotcell stats, included with each result and visible in /cost. There is no dollar or input-token budget that cuts research short. The old workerBudgetUsd and workerBudgetMaxUsd config keys and KIMIFLARE_WORKER_BUDGET_* variables are ignored.

Each subagent uses the same model as the coordinator. Autopilot does not switch models silently.

#Usage stats

/subagents stats summarizes the last 7 days on this machine: sessions, how many offered and used the subagent tool, completion rate, failure categories (repository, hotcell, provider, budget, timeout, cancelled), median duration and total cost. Events are appended to ~/.local/share/kimiflare/subagents.jsonl and contain only session ids, the policy decision, outcomes, durations and costs. They never contain prompts, missions or code.

#If a subagent cannot start

Hotcell setup, repository, provider and timeout failures are reported as tool errors. Autopilot does not fall back to a remote service. The coordinator can continue locally.

The runtime cache record is in ~/.config/kimiflare/hotcell-worker-cache.json.

For the full guide, see docs/subagents.md.