Skip to content
Rhumbatron

Rhumbatron

Rhumbatron is Git, CI, and a distributed task scheduler for autonomous software developers.
Read the architectureDemo runbook

Many agents can propose many futures of one codebase. Only verified evidence can advance the canonical state.

AGENTS.md is the authoritative build plan. docs/BUILD_STATUS.md tracks progress. docs/demo/runbook.md is the demo sequence. docs/architecture/README.md explains the architecture. docs/operations/README.md lists the runbooks.

Live Status

Section titled “Live Status”
Environment Web API Sign-in
prod https://rhumbatron.com (www redirects to the apex) https://api.rhumbatron.com Clerk production instance. Email and password only. Google is off until an OAuth client exists.
dev https://dev.rhumbatron.com https://api-dev.rhumbatron.com Clerk development instance.

Terraform deploys both environments (envs/dev, envs/prod, ADR 0017).

A real model-driven Change ran end to end on dev. The Root Planner and four agents on Gemini via Vertex (MODEL_PROVIDER=vertex) built shared wishlists on stacked workspaces. The Candidate composed automatically. It passed build, 26 unit tests, contract tests, the Cart invariant check, p95 performance, and 9 authorization security tests. A human approved it, and promotion advanced the Canonical Generation from S0 to S1. Model cost was about 0.91 USD.

Architecture

Section titled “Architecture”

docs/architecture/README.md has the full guide. This is the short version.

flowchart LR
  user[User goal] --> api[rhumbatron-api]
  api --> cw[ChangeWorkflow<br/>Root Planner]
  cw --> router[Causal Router<br/>event-router]
  router -->|wake ready Tasks| agent[AgentDO + Pi]
  agent -->|fork| art[(Artifacts)]
  agent -->|run| sbx[Sandbox]
  agent -->|ChangeSet| integ[integration<br/>Candidate + verify]
  integ --> ev[(Evidence<br/>D1 + R2)]
  integ -->|CAS promote| root[ProjectRootDO]
  root -->|outbox| k2[(K2 events)]
  k2 --> router
  router -->|project| view[ProjectViewDO] --> web[rhumbatron-web]

A user submits a goal for a Project. The Root Planner compiles it into a Work Graph of Tasks (ChangeWorkflow). The Causal Router wakes only the agents whose Tasks are ready.

Each agent is an AgentDO with the Pi harness, and it calls models through AI Gateway. The agent declares a typed Intent, works in an Artifacts Workspace inside a capped Sandbox, and publishes a ChangeSet.

Durable Objects hold authoritative state:

  • ProjectRootDO: Holds Canonical Generation and compare-and-swap promotion.
  • ResourceShardDO: Holds Claims and Intents.
  • ProjectViewDO: Holds live read-model and socket state.

Every mutation writes a transactional outbox row, and the outbox publisher sends it to K2. The event router projects Events into the live view and archives them to R2.

A deterministic detector checks Intents on semantic resources. Sonnet reviews ambiguous overlaps and can escalate to Opus. Conflicting paths fork into Candidates.

The integration Worker composes each Candidate and verifies it in the Sandbox (build, unit, contract, Cart invariant, p95, security). It records verification Evidence in D1 and R2.

If the required checks pass and the policy approvals exist, ProjectRootDO promotes the winning Candidate with one atomic compare-and-swap. The promotion advances the Canonical Generation.

Reliability safeguards:

  • Dead-letter consumer with Retry and Dismiss.
  • Section 44 limits (workers/agents/src/limits.ts): 8 active agents and 4 Sandboxes per Change, 2 attempts per tier.
  • Runaway-billing guards (ADR 0019): capped Durable Object alarms, capped causal wakeups, and account budget alerts.
  • Advisory Claims to avoid overlapping writes without rigid locking.

Explore

Section titled “Explore”