What is Nucleic Control?

01What Control is

When you let Nucleic clone and manage a project — it lives under a Nucleic-managed location instead of a folder you picked — that project runs in Control mode. Control is what makes an agent's work on that project observable and contained rather than best-effort.

Three things define a Control project:

• Every session runs inside an isolated Linux sandbox. The agent's tools execute in a per-session container, not loose on your Mac. See how agent sandboxing works for the details.
• Git is observed with certainty. A git interceptor sits ahead of the real git and gh tools and reports each mutating operation — commits, merges, conflicts — back to Nucleic as structured events, not guesses parsed from command output. Nucleic knows what happened because the operation told it, not because it scraped a terminal.
• The control plane runs over a private vsock channel instead of a TCP port. There are no macOS firewall prompts and no exposed ports — the approval and interceptor traffic never touches the network.

Running an agent from an arbitrary directory has none of these guarantees: no sandbox, no certain git observation, no private control channel. Control is the counterpart that adds all three.

02What Control unlocks

Because a Control project is sandboxed and its git activity is observed with certainty, Nucleic can safely automate work that would be risky otherwise. Only Control projects can turn these on:

• Autoship — a finished agent merges its own branch automatically. Merges are safely queued, conflict-aware, and never happen mid-task, so a completed piece of work lands on its own without you babysitting the merge.
• Orchestra — a standing-consent instruction that lets one agent spin up parallel subagents using pre-allowed spawn tools, so a single request can fan out into coordinated parallel work.
• nvrsion (Beta) — shared-trunk versioning where agents edit one trunk checkout and each edit lands instantly as its own path-scoped commit, instead of juggling branches.

03Turning it on

Control is built on the container service, so it comes on in two moves — enable the container service first, then turn Control on.

1. Enable the container service

   In Settings ▸ Sandbox, turn on Enable container service. This is the sandbox that Control sessions run inside — see the Sandboxes guide for what it does and how it works.

2. Turn on Nucleic Control

   In Settings ▸ Control, turn on Enable Nucleic Control on all projects — or enable Control per project as you clone it, if you'd rather opt in one at a time.

3. Optionally use nvrsion for new projects

   If you want shared-trunk versioning, also turn on Use nvrsion for new Control projects (Beta). New Control projects will then be set up on nvrsion.

04Requirements

Control has the same platform floor as the sandbox it runs on:

• macOS 27 or later on Apple silicon. Required to run the sandbox that Control is built on.
• A one-time download on first use. The first time you use Control, Nucleic downloads and caches a small Linux kernel and the sandbox root image (about 14 GB). This happens once; later sessions reuse the cached image.

For a full picture of what the sandbox is and how the agent's tools run inside it, see how agent sandboxing works. If you also run macOS VMs alongside Control projects, the macOS virtual machines overview covers that separate service.

05Advanced Control options

A few extra toggles live under Settings ▸ Control for people who go looking. Leave the defaults unless you have a reason to change them:

• Agent Lifecycle Protection — guards a running agent's container from being torn down out from under it.
• Control plane over vsock — routes the approval and interceptor traffic over vsock rather than a gateway TCP port. This is the default.
• Trace shell commands — records the shell commands agents run, for observability.