Architecture
The control plane governs tasks. Sandboxes host execution. Every layer has a clear responsibility.
Components and responsibilities
Task sandbox · one per task
GatewayWeb / WebSocket → sandbox access
Contracts & LibrariesShared protocols and semantics
Component responsibilities and state authority
- 01
Control Plane
Carries product use cases and the governance boundary: identity, scope, version authority for flows and capabilities, task provisioning and dispatch, knowledge governance, audit and transport adaptation.
State authorityAuthoritative for structured business state, in PostgreSQL.
- 02
Agent Runner
Advances nodes and attempts within a granted execution generation, runs native agent sessions and events, and handles dependencies, bounded concurrency, cancellation and completion.
State authorityAuthoritative for the DAG, attempts, session references and runtime events.
- 03
Sandbox Provider
Owns creation, observation, binding and cleanup of runtime environments. Three implementations ship independently behind one protocol.
State authorityAuthoritative for environment lifecycle. A ready environment does not mean the work succeeded.
- 04
Sandbox Gateway
Unifies web and WebSocket access, in-page terminals, and the runner's remote procedure entry.
State authorityTransport adaptation only; it holds no business state authority.
- 05
Console
Composes product APIs and controlled interaction into a role-aware desktop workbench.
State authorityHolds no second authority over execution or authorisation; it presents control-plane facts.
- 06
Contracts and Libraries
Cross-component protocols and semantic contracts, plus independently reusable foundational capability.
State authorityComponents never import each other's internals — only explicit contracts.
Why it is built this way
These trade-offs define the platform's shape. They were not chosen for implementation convenience — each one refuses a specific kind of complexity.
Scheduling and state share one failure domain
DAG state, sessions, artefacts and Git worktrees all live inside the task's own sandbox. The supervisor in that sandbox is the only scheduling authority, and the control plane keeps no node-level state.
Consequence：Buys a simple, consistent state model. The accepted cost is that permanently losing a sandbox fails the whole task, with no recovery from a node checkpoint.
Completion is proven by contract, not asserted in prose
Each node's success condition is defined by declared artefacts, a manifest file, a result summary and quality gates, all enforced at runtime. An incomplete format or coverage fails the node.
Consequence：An agent cannot bypass delivery requirements by saying the work is done. Project instructions or model drift cannot override the completion contract.
Flows can be generated and still versioned
Ordinary users describe the task. The platform prefers reusing a published flow and generates a task-scoped flow only when none fits — both passing the same deterministic compiler and digest verification.
Consequence：Lowers adoption cost without giving up reproducibility. A generated flow never becomes a team asset automatically; reuse requires explicit promotion.
Knowledge needs both governance and an execution surface
Users maintain and review knowledge, while agents query the latest effective content at runtime through a read-only interface that rechecks subject, scope and authorisation on every call.
Consequence：Storage and a UI without a runtime consumption interface is not a complete knowledge product — and the runtime cannot bypass governance to search directly.
Credentials are injected to the smallest possible receiver
Member model keys go only to the runner, local extension credentials only to their sidecar, remote extension credentials only to the proxy. The task secret is deleted once components are ready.
Consequence：The main agent process never holds extension credentials, and secrets never enter images, repositories, specifications, logs or events.
Enterprise edition assumes pure private deployment
The control plane, sandboxes, model access, artefacts and telemetry all run standalone inside the customer environment, depending on no externally hosted service.
Consequence：Every state authority must be deployable inside the customer's network. This rules out designs that place a managed service on the critical path.
Which fact is stored where
Structured business state lives in the control plane's relational database. The runner atomically stores execution generations, events and recovery receipts in a local transactional journal. Source-of-truth facts live in Git. Large objects — runtime snapshots, frozen requirements and capability bundles — enter object storage under their own contracts. Knowledge bodies and indexes are held by a separate retrieval data plane, and personal memory uses its own database and account with no foreign keys or shared transactions against the control-plane database. Execution generation, environment generation and writer epoch are independent: cancellation acceptance, process exit, durable terminal state and business success are distinct facts, and a side effect lacking exit evidence stays unknown rather than being automatically replayed.