# 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

| Preset        | Installs                                             |
|---------------|------------------------------------------------------|
| `blank`       | Nothing — a clean base VM                            |
| `node`        | Node.js toolchain                                    |
| `python`      | Python toolchain                                     |
| `swift`       | Swift toolchain                                      |
| `claude-code` | Node + `@anthropic-ai/claude-code`                   |

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:

| Isolation           | `--home-mount` | What the sandbox can see of your host                          |
|---------------------|----------------|----------------------------------------------------------------|
| **Isolated** (default) | `none`      | Nothing. Your `$HOME`, SSH keys, and cloud tokens are invisible. |
| **Read-only**       | `ro`           | Your home directory, read-only. Credentials become readable.   |
| **Read-write**      | `rw`           | Your home directory, read and write. Full exposure.            |

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](agent-setup.md)).