01What the sandbox is
When you sandbox a session, Nucleic runs the coding agent inside its own isolated Linux VM — a fresh one per session, spun up on demand and thrown away when it's done.
The VM is built on Apple's in-process containerization framework — the same API behind Apple's container CLI. It's not Docker, and there's no background daemon: everything runs inside the Nucleic app process. Because the VMs are bounded by that process, they're torn down when Nucleic quits and recreated on demand the next time you launch.
The agent itself is spawned as a container process, and its input and output ride a vsock channel back to the host. That means Nucleic drives the sandboxed agent exactly the way it would drive a plain local process — the sandbox is transparent to everything upstream. Your project's git worktree is bind-mounted into the container, so the agent edits the same files you'd expect, just from inside the VM.
02What it isolates
Each sandbox is walled off along three axes — files, network, and the host — so a session can't reach past its own boundary.
- Files. Concurrent sessions get separate mounts and cannot corrupt each other's files. Every session sees its own worktree and nothing else.
- Network. The container reaches the network through a NAT'd virtual interface. It has internet egress — enough for
git,npm, and agent-provider API calls — but no inbound exposed ports. Nothing on your network can reach into the sandbox. - The host. The control plane — the approval server plus the git and command interceptors — talks to the host over
vsock, not over a network socket. Because that channel isn't network traffic, there are no macOS firewall prompts to click through.
The net effect: a sandboxed agent can do its work and phone out to the services it legitimately needs, while staying isolated from your Mac and from every other running session.
03Turning it on
Sandboxing is controlled from one place, with a per-project default you can opt into:
-
Enable the container service
In Settings ▸ Sandbox, turn on Enable container service. This starts the containerization layer that hosts the per-session VMs.
-
Optionally sandbox new projects by default
Turn on Sandbox new projects by default so every new project starts sandboxed. You can still flip sandboxing per project afterward.
04Per-project options
Each project's sandbox can be tuned independently. The knobs live in the project's settings:
| Option | What it does |
|---|---|
| Sandboxing | Turn the sandbox on or off for this project. |
| Image | Point the sandbox at a custom container image instead of the default root image. |
| Idle timeout | How long the container can sit idle before it stops to free resources — default 15 minutes. It reboots quickly on the next turn, so the pause is nearly invisible. |
| Host exec | Allow the approval-gated host_exec tool, which lets the sandboxed agent run a command on the host Mac. It's never auto-approved — every call is gated on your explicit approval. |
| Setup script | A per-project setup script that runs at session start — the place to install dependencies before the agent gets going. |
05Why the Swift/Xcode toolchain isn't inside
The sandbox image deliberately omits the Swift/Xcode toolchain — the container is Linux, and it simply can't run it. So Mac-only work — Swift builds, xcodebuild, codesign, simulators — has to escape the sandbox. There are two ways out:
| Path | What it is |
|---|---|
| host_exec | Runs the command on the shared host Mac. It's concurrency-gated, so parallel agents don't thrash the one host. Good for occasional Mac-side commands, but it shares a single machine across sessions. |
| macOS VM (preferred) |
Gives each session its own isolated Mac through mac_vm_exec. Because every agent gets a separate VM, this is the path to use for parallel Mac builds — sessions don't contend for one shared host. |
For anything more than a stray Mac-side command — and especially when several agents are building at once — reach for a per-session macOS VM rather than piling everything onto the shared host through host_exec.
host_exec is fine. Real Mac builds, or several agents building in parallel? Give each one its own macOS VM.06Requirements & storage
Sandboxing needs macOS 27 or later on Apple silicon.
On first use, Nucleic downloads and caches two things under its Application Support folder:
- A Linux kernel — small.
- The sandbox root image — about 14 GB.
That first download is a one-time cost. Later sessions reuse the cache, so spinning up a new sandbox is fast and doesn't re-fetch anything.