Agent Sandboxes

An Agent Sandbox is a disposable container machine VM you can hand to a coding agent — a place for Claude Code (or any tool) to clone a repo, install packages, and run commands off your host machine. When you're done, you throw it away.

This page is deliberately blunt about the isolation model, because the honest version is the only version worth trusting.

Creating a sandbox

From the UI: Sandboxes ▸ New. Pick a preset, pick an isolation level, and watch the setup stream live in the create sheet. From an agent: the sandbox_create MCP tool (permission-gated).

Presets

Setup provisioning runs as root inside the VM (an early build ran as uid 502 and couldn't install packages — the claude-code preset was broken without the --root fix), with a bounded retry for the post-create boot race.

The isolation model (read this)

Here is the honest constraint: the only host-filesystem lever Apple's container machine command offers is --home-mount, with three values:

That's the whole lever. There are no other mount flags and no network-isolation flags on machine create — the isolation story is --home-mount and nothing else. We don't pretend otherwise.

Why the default is none

The moment you choose ro or rw, the agent in the sandbox can read your ~/.ssh keys, your ~/.aws and ~/.config credentials, your cloud tokens — anything under your home directory. So:

• Isolated (none) is the default, and it's what the 60-second demo uses.
• The ro and rw options are presented with explicit, red-text credential-exposure warnings in both the create sheet and the isolation badge on each sandbox row. You are told, in plain language, exactly what you're exposing before you commit.

Only loosen isolation when you have a concrete reason and you understand that the agent gains your credentials for the duration.

Working in a sandbox

• In-app terminal — open a real PTY (SwiftTerm) straight into the VM via machine run -it.
• Copy your repo in — container cp moves files into the sandbox's backing container. (The backing container ID rotates on each machine run; the app resolves and retries so copy-in stays reliable.)
• Drive it from an agent — sandbox_run executes a command inside the VM. Note that sandbox_run stdout is best-effort: the VM console relay can drop early output.

Resetting and deleting

• Reset from profile rebuilds the sandbox clean from its preset — no snapshots to manage.
• Delete throws it away entirely.

One deliberate non-feature: there is no export/rollback. A machine's backing container is ephemeral — while running it's locked, and once stopped it's gone — so container export can never reach it. Rather than ship a rollback that can't actually work, the app offers an honest reset. That's a limitation of the runtime, stated as one.

In short

• Default is airtight (none); anything looser warns you in red.
• The sandbox is disposable by design — reset or delete, no state to babysit.
• Manage it from the UI or via seven permission-gated MCP tools (see agent setup).