01What the sandbox is
When you sandbox a session, Nucleic runs the coding agent in its own isolated Linux VM. A fresh one for every session — created on demand, gone when the session ends.
The VM is built on Apple's in-process containerization framework — the same API behind Apple's container CLI. It isn't Docker, and there's no background daemon. Everything runs inside the Nucleic app process, so VMs are torn down when Nucleic quits and recreated on demand the next time you launch.
The agent runs as a container process, with its input and output carried over a vsock channel back to the host. So Nucleic drives a sandboxed agent exactly as it would a plain local process — the sandbox is invisible to everything upstream. And because your project's git worktree is bind-mounted into the container, the agent edits the files you expect, just from inside the VM.
02What it isolates
Each sandbox is isolated in three ways — files, network, and the host — so a session can't reach past its own boundary.
- Files. Every session sees its own worktree and nothing else. Concurrent sessions get separate mounts, so they can't corrupt each other's files.
- 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. That channel isn't network traffic, so there are no macOS firewall prompts to click through.
The result: a sandboxed agent can do its work and reach the services it legitimately needs, while staying isolated from your Mac and from every other running session.
03Turning it on
You control sandboxing in one place, with a default for new projects 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 change it for any project later.
04Per-project options
You can tune each project's sandbox independently. These options live in the project's settings:
| Option | What it does |
|---|---|
| Sandboxing | Turn the sandbox on or off for this project. |
| Image | Use 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 — 15 minutes by default. It reboots quickly on the next turn, so you'll barely notice the pause. |
| 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 waits for your explicit approval. |
| Setup script | A per-project setup script that runs when the session starts — the place to install dependencies before the agent gets to work. |
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 leave 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 overwhelm the one host. Good for the occasional Mac-side command, but every session shares a single machine. |
| macOS VM (preferred) |
Gives each session its own isolated Mac through mac_vm_exec. Every agent gets a separate VM, so this is the path for parallel Mac builds — sessions never compete for one shared host. |
For anything more than the occasional Mac-side command — especially when several agents are building at once — use a per-session macOS VM instead of sending everything to 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 requires macOS 27 or later on Apple silicon.
The first time you use it, Nucleic downloads and caches two things under its Application Support folder:
- A Linux kernel — small.
- The sandbox root image — about 14 GB.
You download it once. Every session after that reuses the cache, so new sandboxes start fast — nothing is fetched again.