Remote runners
A runner lets a conversation use another computer's CPU, memory, disk and toolchain while your original sandbox keeps the conversation, transcript, review and land workflow. Execution moves; control does not.
On this page(8 sections)
What a runner is
A runner is the ordinary sandbox image booted in an execution-only mode. It belongs to a parent sandbox, not to a person: there is no browser owner, member list, public hostname or second fleet to visit. The runner dials its parent over one outbound connection, so a laptop behind NAT and a VM on a private network have the same posture.
It keeps the expensive parts that make a remote turn behave like a local one: the same daemon turn machinery, harnesses, terminals, dependency installation, approved environment overlay and optional nested Docker engine. It leaves account identity, review state and workspace authority with the parent.
Parent owns the work; runner performs it
| Concern | Parent sandbox | Runner |
|---|---|---|
| Conversation identity and status | Owns it | Receives the id for the dispatched turn |
| Transcript and interactive cards | Persists and displays them | Streams events; receives answers and steering |
| Working tree | Keeps the branch mirror used by diff and land | Checks out and edits the active copy |
| Agent process and tools | Plans and dispatches | Runs the harness, commands, tests and runtime subagents |
| Review and landing | Owns the only land door | Pushes the resulting branch back |
The browser never contacts the runner. A question, plan or permission card raised there streams to the parent, and your answer is forwarded to the machine that raised it. Stop and mid-turn steering travel the same way. From the fleet board, a remote conversation differs only by its placement label and the fact that an offline machine is a named failure rather than a hanging spinner.
One turn across the link
- Prepare. The parent creates the isolated conversation and asks the runner to fetch that conversation's branch for every repo. A remote conversation is always isolated.
- Run. The runner starts the selected provider and harness, materialises any attachments, and streams the same typed events a local turn would produce.
- Return. However the turn ends, the runner snapshots and pushes its branch back. The parent advances its mirror worktree, so the existing diff, standing, archive and land code sees the result without a remote-specific path.
- Review. You inspect and land from the parent exactly as you would for a locally executed isolated agent.
Dependencies and build outputs are rebuilt and kept warm on the runner rather than copied between architectures. Git moves source; caches stay where they were produced. That avoids treating an ARM laptop's node_modules or native build output as valid on an x86 VM.
Add a runner to a computer
First connect the computer from Sandbox → Devices and allow it to Manage sandboxes. That switch is the machine-local permission to create and update containers; adding a runner does not widen shell, screen or file access.
On that computer's card, use Runners for this sandbox → Add runner, give it a name, and watch the same host-side container flow used for ordinary sandbox operations. The parent mints a single-use pairing, injects its own address, and receives the runner's dial-back. Removing it revokes the enrollment after the machine confirms the container is gone.
A runner started by hand can still connect and run turns. It appears in the placement picker, but not under a computer card when no connected host identity says which machine owns its lifecycle.
Place a conversation
A new agent's Where this runs picker lists this sandbox and every online runner, with CPU, memory and load. Placement is chosen when the conversation is created and then latched: its branch and warm working tree belong on one machine, so a later picker that silently did nothing would be worse than no picker.
Full child agents created by the meta-harness are placed automatically. The scheduler prefers the machine with the most free agent slots, breaks ties by current load, and falls back to the parent instead of waiting for an offline or busy laptop. Capacity is bounded by both cores and memory; outdated runners remain usable because drift is reported rather than turned into a surprise refusal.
An agent may override the scheduler when the task genuinely needs one machine:
agents spawn --provider claude --on build-rig 'Run the Linux test matrix'
agents spawn --provider codex --on here 'Review the result and prepare the patch'The environment is replicated by definition
Creating a runner builds it from the parent's image and byte-identical approved overlay before it starts. The parent also sends a settings-only sandbox definition. Repository entries are intentionally ignored — the exact conversation branches arrive through git — and capability and secret entries are stripped.
Each runner reports its image, release channel, overlay hash and settings. Its card shows current, outdated or unknown, plus the individual drift lines. Settings can be synchronised over the live link. An overlay difference needs the container rebuilt, because adding a compiler is an image change, not a settings call.
Credentials and capabilities
A runner does not inherit the parent's browser sessions, connected devices, capabilities or secret values. Model access is the narrow exception required to execute the selected turn: Claude Code-family harnesses resolve against the parent's connected account, receiving a per-turn access token or using the parent's authenticated model translator as a service. Long-lived refresh credentials stay at the origin.
Native runtimes whose login lives in their own CLI home — including native Codex, Gemini, Cursor and ACP agents — use the runner's local login. Automatic child placement keeps those runtimes on the parent unless their credential is known to travel; an explicit placement remains available when you know that runner is signed in.
Failure is bounded by the branch
- Runner offline before a turn: the conversation says which runner is unavailable and does not silently execute elsewhere.
- Link lost during a turn: the turn is interrupted; completed pushes remain at the parent and the runner keeps its local checkout for the next sync.
- Runner removed: the parent still has the conversation, transcript and last delivered branch, so work can continue in a new conversation here or on another runner.
- Parent restarts: the runner reconnects with its durable enrollment; the single-use pairing is not replayed.
Related pages
- Parallel agents: isolated branches, meta-harness children and landing.
- Your own machine: enrolling the computer and enforcing its grants locally.
- Sandbox definitions: the TOML contract used to reproduce settings and environment shape.
- Models & accounts: the provider, account and harness whose credential the turn spends.