The parts
- Console
TanStack Start and React. Pages are served here; every domain request and live stream goes to Rust.
- Orchestrator
One Rust process. Owns the database, starts and watches sandboxes, routes work, encrypts secrets, and is the only thing that touches the cluster.
- PostgreSQL
The source of truth: agents, conversations, memory, skills, files metadata, the audit log. Agents never connect to it.
- Agent sandboxes
One per agent, always on. The agent runtime, its tools, its desktop and its journal live together inside it.
Agents call model providers and your connected accounts themselves, from inside their sandbox, with short-lived credentials the orchestrator hands them. The orchestrator never runs an agent's tools for it.
What happens when you send a message
- The console sends your message to the orchestrator, which stores it and queues a turn for the agent.
- The agent holds an open channel to the orchestrator and receives the turn: your message, its instructions, its history and the tools this turn may use.
- It calls the model, streaming text back as it arrives. When the model asks for tools, it writes each call to its journal first, then runs them, several at once when it can.
- Events wait in an outbox until the orchestrator acknowledges them, so a dropped connection loses nothing.
- When the model is done, the agent saves what is worth remembering and the turn is committed.
The sandbox
The sandbox is the trust boundary: an agent and everything it runs live in it together, with only that agent's authority. The installation declares one of two runtimes, and the console always shows which.
kvm: a virtual machine per agent
cubebot-sandbox is an in-house VMM written in Rust on KVM ioctls, with no third-party VMM crates. Each guest gets a Linux kernel, a read-only root image, a persistent workspace disk, a network device and a vsock control channel, 2 vCPUs and 2 GiB of memory by default. Its network traffic leaves through a tap device in the pod's own namespace, so network policy applies to exactly one agent. It needs x86_64 Linux.
container: the same image, directly
The agent image runs as a container with a minimal set of capabilities. It has the same tools, desktop and recovery, shares the host's kernel, and works on any Docker host, every Mac included. An administrator can add a stronger runtime class such as gVisor.
The desktop
Inside each sandbox, one arbiter owns the screen and the input. It knows whether the agent, a watcher or a person is in control, refuses the agent's input while a person holds it, and streams only the parts of the screen that change. The orchestrator relays the picture but never stores a person's session.
Recovery
- One orchestrator is active at a time, holding a lock in PostgreSQL. A replacement waits for proof the old one stopped.
- Interrupted turns are recovered on every reconcile pass. A tool call whose outcome is unknown waits for a person.
- Sandboxes carry an epoch, so a stale one cannot write to the ledger after it was replaced.
Read the decisions
Every behavior above comes from an accepted decision record. They are short, dated and honest about what is still open.
- ARCHITECTURE.md, the whole system on one page
- Decision records for agents, sandboxes, memory, rooms, identity, the console and packaging
- The manifesto, for why it is built this way