Sandboxes
On a runner with a container runtime, each newly created worktree runs inside its own container. An agent working in one worktree cannot see the host, the other worktrees, or anything you did not hand it.
When it turns on
Two conditions, both checked at startup:
| Condition | Detail |
|---|---|
| A container runtime is installed | podman or docker, whichever answers first |
| The machine is a runner | Not a desktop — a laptop with Docker installed never sandboxes |
Both true and sandboxing is on; the app reports which runtime it found. Either false and everything behaves exactly as it always has. There is no switch to flip and nothing to configure.
It applies to newly created worktrees only. Worktrees that already existed keep running on the host, and every desktop worktree is unaffected.
What it isolates
Each sandboxed worktree gets its own container, holding its own checkout and its own agent processes. The isolation is from the host and from the other worktrees on the same box — not from the network.
Two design details are worth knowing because they shape what you will see:
The git layout changes. A sandboxed worktree hangs off a bare clone of its repo rather than your normal checkout, because the container has to mount the git directory too and mounting a whole clone would bring every other worktree in with it. The bare repo and the worktree are mounted at identical paths inside and out, since git records worktrees by absolute path.
Terminals still survive. ptyd stays on the host and executes into the
container, so agent sessions live through daemon restarts and server upgrades
exactly as they do everywhere else. Stopping the container does end its live
sessions; the next attach starts it again.
Credentials
Agent CLIs live in a base image that the runner builds locally from the repo's own declared Node version.
Your credentials are not in that image. The model key and git identity are
written to a 0600 env file and injected when the container starts, so they
never end up baked into an image layer. Agent status reaches the host over a
bind-mounted socket that is itself restricted to the status routes and nothing
else.
Heads up
A container carries the credentials and hook mounts it was created with. Changing either takes recreating the worktree — restarting the container is not enough.
Idle containers
A sandbox that has seen no activity for two hours is stopped, and starts again the next time you attach to it. A worktree created moments ago is never parked on first sight.