Core concepts

FSM orchestration

Approving turns coding agents into steps in a workflow. You orchestrate on a finite state machine:

• Nodes are states (agent / react / gate / …)
• Edges are transitions, with configurable success, failure, and rollback paths
• Use when guards and checkpoints to make risky steps explicit

This is not a one-shot, irreversible agent run: design the path first, then gate the critical steps.

Human gates

When a step needs a human decision, the run stops at a gate until someone approves or rejects.

Approval moments are first-class — not an afterthought. Approving bets that agents can be fast while people still own the critical decisions.

Real Docker sandboxes

Agents are not black-box prompts on a laptop. They execute in Docker containers through the in-repo sandbox-gateway, talking over ACP.

Supported backends: Cursor, Claude Code, CodeBuddy, and Trae. Configure acpBackend per agent; keep secrets in agent meta env.

Artifact contract and MCP

Each run has an isolated artifact MCP. Agents call tools such as:

• write_artifact
• set_*
• node_complete

Isolation is by run token, leaving an inspectable paper trail.

Single-repo self-hosting

sandbox-gateway and the generic sandbox image sources live in this repository. One clone is enough to self-host.