# How agent sandboxing works — Nucleic Support
How Nucleic sandboxes coding agents: each session runs in its own lightweight Linux VM on Apple's containerization framework, isolated from your host and from other sessions.

Sandboxes

# How agent sandboxing works

Every sandboxed session runs in its own lightweight Linux VM, built on Apple's containerization framework — isolated from your Mac and from every other session.

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

Good to knowThere's nothing to install and no daemon to keep running. The container service lives and dies with the Nucleic app — quit Nucleic and every sandbox VM goes away with it.

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

1. ### Enable the container service

   In Settings ▸ Sandbox, turn on Enable container service. This starts the containerization layer that hosts 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 flip sandboxing per project afterward.

Control keeps it onWhile any Nucleic Control project exists, the container service is pinned 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 the last Control project and the toggle unlocks again.

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

Idle, not goneAn idle-stopped container isn't discarded — its state comes back on the next turn after a quick reboot. The timeout just keeps parked sessions from holding 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 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`.

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

## Related guides

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