Cubebot

How Cubebot is built

Three services and one sandbox per agent. Everything is Rust except the console, and every important decision is written down in the open.

The parts

  1. Console

    TanStack Start and React. Pages are served here; every domain request and live stream goes to Rust.

  2. Orchestrator

    One Rust process. Owns the database, starts and watches sandboxes, routes work, encrypts secrets, and is the only thing that touches the cluster.

  3. PostgreSQL

    The source of truth: agents, conversations, memory, skills, files metadata, the audit log. Agents never connect to it.

  4. 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

  1. The console sends your message to the orchestrator, which stores it and queues a turn for the agent.
  2. 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.
  3. 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.
  4. Events wait in an outbox until the orchestrator acknowledges them, so a dropped connection loses nothing.
  5. 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.

Free, open and yours to keep.

Cubebot is Apache-2.0 and self-hosted, with no paid tier and no account to create. One person builds it in the open. A star helps others find it; a sponsorship buys the time to keep building.