Nucleic
Nucleic Control

What is Nucleic Control?

With Nucleic Control, Nucleic clones, sandboxes, and observes a project itself. It's the secure, watched alternative to pointing an agent at any folder — and the foundation for unattended work.

01What Control is

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

Three things define a Control project:

  • Every session runs inside an isolated Linux sandbox. The agent's tools run in a per-session container — not loose on your Mac. See how agent sandboxing works for details.
  • Git is observed with certainty. Nucleic knows what an agent did to git — commits, merges, conflicts, pull requests — reported as they happen, not guessed at from terminal output.
  • The agent's link to Nucleic never touches the network. No macOS firewall prompts, no open ports.

Run an agent from an arbitrary folder and you get none of these guarantees: no sandbox, no certain git observation, no private control channel. Control 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 exist only 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 otherwise be risky. 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 completed work lands on its own. No babysitting the merge.
  • Orchestra — a standing-consent instruction that lets one agent spin up parallel subagents using pre-allowed spawn tools. A single request fans out into coordinated parallel work.
  • nvrsion (Beta) — shared-trunk versioning. Agents edit one trunk checkout, and each edit lands instantly as its own path-scoped commit — no juggling branches.
Why these need ControlAutoship and Orchestra depend on Nucleic knowing exactly what an agent did — and being able to contain it. Control's sandbox and certain git observation 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 setup takes two moves: turn on the container service first, then turn on Control.

  1. Enable the container service

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

  2. Turn on Nucleic Control

    In Settings ▸ Control, turn on Enable Nucleic Control on all projects. Or, if you'd rather opt in one project at a time, turn on Control for each project as you clone it.

  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 are then 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 ask you to turn it on first. Turn on Settings ▸ Sandbox ▸ Enable container service, then come back.

04Requirements

Control needs the same platform 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.

To learn 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

Two additional toggles live under Settings ▸ Control. Leave the defaults unless you have a reason to change them:

  • Agent Lifecycle Protection — keeps a running agent's container from being torn down out from under it.
  • Trace shell commands — records the shell commands agents run, for observability.

Related guides

How agent sandboxing works macOS virtual machines: overview