# What is Nucleic Control? — Nucleic Support
What Nucleic Control is: the hardened path where Nucleic clones, sandboxes, and observes a project directly — unlocking unattended work, Autoship, and Orchestra.

Nucleic Control

# What is Nucleic Control?

Nucleic Control is the hardened path where Nucleic itself clones, sandboxes, and observes a project — the secure, watched counterpart to running an agent from an arbitrary folder, and the foundation for unattended work.

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

The distinctionA project is either Control (Nucleic clones and manages it, and the guarantees above apply) or an ordinary folder you point an agent at. The features below only exist for Control projects — that's the whole reason to use one.

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

Why these need ControlAutoship and Orchestra hinge on Nucleic knowing exactly what an agent did and being able to contain it. The sandbox and certain git observation of Control are what make unattended merging and parallel spawning safe — which is why they aren't offered for arbitrary folders.

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

If the toggles are greyed outThe Control toggles depend on the container service. If it's off, they're disabled and prompt you to turn it on first — enable Settings ▸ Sandbox ▸ Enable container service, then come back.

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

## Related guides

How agent sandboxing works→ macOS virtual machines: overview→