# How agent sandboxing works — Nucleic Support
Nucleic runs every sandboxed coding session in its own lightweight Linux VM — isolated from your Mac and from every other session.

Sandboxes

# How agent sandboxing works

Every sandboxed session gets its own lightweight Linux VM. Isolated from your Mac. Isolated from every other session.

## 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.

Good to knowNothing to install. No daemon to keep running. The container service lives and dies with the Nucleic app — quit Nucleic, and every sandbox VM goes with it.

## 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:

1. ### Enable the container service

   In Settings ▸ Sandbox, turn on Enable container service. This is what runs the per-session VMs.

2. ### 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.

Control keeps it onWhile you have any Nucleic Control project, the container service stays on and the toggle is locked — Control can't run without it. You'll see "Required by your Nucleic Control projects, so it stays on." Remove your last Control project, and the toggle unlocks.

## 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.

Idle, not goneAn idle-stopped container isn't discarded — its state comes back after a quick reboot on the next turn. The timeout simply keeps parked sessions from holding onto resources.

## 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`.

Rule of thumbOne-off Mac command? `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.

## Related guides

What is Nucleic Control?→ macOS virtual machines: overview→