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.
It's a real Linux VM, not a shared runtime — and there's no background daemon to babysit. Sandboxes are torn down when Nucleic quits and recreated on demand the next time you launch.
Nucleic drives a sandboxed agent exactly as it would a plain local process — the sandbox is invisible to everything upstream. The agent edits the files you expect, from inside its own machine.
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 sandbox can reach out to the internet — enough for
git,npm, and agent-provider API calls — but nothing on your network can reach into it. - The host. The parts of Nucleic the agent talks to are reached without ever touching the network, so there are no macOS firewall prompts to click through and no open ports.
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 is what runs 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.