Architecture
Nucleus is a hosted control plane that holds the factory’s issues, workflows, rules and evidence. For each agent task it provisions a sandbox, runs a coding harness inside it with a prepared briefing, and records what comes back. People direct and approve the work through the web app and GitHub.
Each box is a subsystem with its own state. Inside the control plane, Issues holds intent and workflow plans; Workflows holds definitions, runs and routing; Context and skills holds briefings and versioned skills; Governance holds policies, approvals and decisions; Evidence holds artifacts, evaluations and findings. Integrations holds the GitHub connection, the sandbox provider and the credential vault, and Runtime provisions sandboxes and issues invocations and tool grants.
The three layers
Section titled “The three layers”- People and tools are where work is requested and decided. Your team raises issues, reviews artifacts and approves or rejects them in the web app, the PWA or through GitHub. GitHub issues and pull requests are mirrors of Nucleus records, so a change made on either side is reconciled by the control plane.
- The control plane is the Nucleus backend. It owns the issue, the versioned workflow definition, each run’s progress, the briefing an agent receives, the skills it is given, the policies and approvals that govern progression, and the evidence a run leaves behind. It talks to GitHub for issues, pull requests, checks and deployments, and to the sandbox provider to create and clean up execution environments. It never runs an agent itself.
- Execution is a sandbox provisioned for one invocation. A provider adapter creates or attaches the environment, checks out the source and materialises the credentials the invocation selected. A resident process inside the sandbox then brokers tool and MCP access through the grants it was given, starts the harness, and sends bounded status and evidence back. The harness (Claude Code, Codex CLI, OpenCode, Gemini CLI or Cursor CLI) calls the model provider and edits the checkout.
What moves between the layers
Section titled “What moves between the layers”Work moves down and evidence moves up. Between people and the control plane, the downward path carries new issues, decisions and approvals; the upward path carries the inbox, run status and the artifacts waiting for review.
Between the control plane and execution, the downward path is a single runtime invocation. It carries the placement decision, the source to check out, a deterministic briefing assembled from the issue and the task’s declared inputs, the exact versions of the skills the task uses, and the tool grants the task is allowed. The upward path carries the artifacts the task produced, telemetry and usage, and the results of any checks. That evidence is input to the control plane’s decisions. An agent’s report that a task is complete does not advance the workflow by itself; the workflow’s evaluations, routing rules and approvals do.
How a run executes
Section titled “How a run executes”- An issue enters the factory, raised in Nucleus or mirrored from GitHub, and a workflow plan selects the workflow that applies.
- The control plane starts a workflow run and advances it node by node. Each agent task node becomes a runtime invocation with a briefing, pinned skill versions, a harness and model, and its tool grants.
- Provisioning places the invocation on a sandbox provider. The provider adapter creates or attaches the sandbox, checks out the repository and materialises the selected credentials in provider-local form. Sandboxes are hosted today; a macOS host is planned as another provider on the same substrate.
- The resident starts inside the sandbox with a launch context it does not need to rediscover. It validates its grants, starts the harness, and supervises it. The agent reads the briefing, uses its skills and tools, and writes its outputs.
- Outputs return as workflow artifacts with a recorded execution attempt, telemetry and accounting. Resident evidence is classified by the control plane; it is an observation, not a verdict. Evaluator tasks judge the artifacts and record findings.
- Routing is deterministic over those results: advance, revise with findings, stop, or wait for a person. Approvals and decisions are recorded in the governance ledger, and a pull request on GitHub carries the resulting change.
Atomic workflows explains why work is divided this way. Workflow engine shows a real definition.
Where things run
Section titled “Where things run”| Component | Runs | Talks to |
|---|---|---|
| Web app | In your browser, hosted by Nucleus | The control plane |
| Control plane | Hosted Nucleus backend | GitHub, the sandbox provider, model provider accounts |
| Sandbox, resident and harness | An environment provisioned for one invocation | The control plane, the repository checkout, the model provider |
| Model provider | Anthropic, OpenAI or another vendor | Called by the harness with credentials the invocation selected |
Model provider credentials are held by the control plane’s vault and materialised into the sandbox for one invocation. The agent works with what the invocation grants; nothing else on the host counts as authority.
What each layer does not own
Section titled “What each layer does not own”The harness does not own the workflow. It runs one task and returns; which task exists, what it receives and what must come back are declared in the workflow definition.
The agent does not own authority. Its instructions say what to do; tool grants, repository permissions and approval policies determine what it can do. See Factory governance for how those policies attach to exact subjects.
The sandbox does not own the outcome. The resident reports what happened. Whether an artifact is accepted, revised or rejected is decided in the control plane after its evaluations and any required approval.
Keep reading
Section titled “Keep reading”- Software factory for the division of work between people, agents and deterministic process.
- Context orchestration for how the briefing is assembled.
- Security model for credential custody and execution isolation.