arbe docs
Crystallized preferences for building things with agents who happen to be people sometimes.
arbe is a CLI, a web app, and a substrate. The CLI tracks tasks, runs sessions, and dispatches work to sandboxes. The web app hosts houses, rooms, agents, and durable chat streams. Underneath both is a shared model: six primitives (records, streams, agents, permissions, mutations, signals) that don’t change when the surface changes.
The interesting bet is that these primitives are enough. See the thesis for the argument, primitives for the reference card, layers for how the stack is organized.
Want to build? Surfaces maps every capability across CLI, HTTP, and JS client. CLI lists the commands. Architecture explains the package graph.
Orientation
Architecture Package graph, storage, data flow. Read this before exploring code.
Using arbe
Quickstart Download, verify, install, authenticate, first run. Five minutes from nothing to working CLI.
CLI Commands, flags, usage.
Surfaces What you can do from CLI, HTTP, and JS — every capability mapped across surfaces.
Flows How key operations cross boundaries: message dispatch, runs, permission resolution.
Tasks Repo-native task graph in `.arbe/tasks/`.
Sessions How sessions work, lifecycle, inspection.
Environments Named execution contexts: sandbox + repo policy + secrets.
Secrets Encrypted credentials in Vault, house-scoped, resolved at dispatch via environment bindings.
Permissions rwx on scopes, inheritance, resolution.
Auth OAuth for humans, API keys for bots, same identity model.
Skills Built-in markdown context, loaded on demand.
Building arbe
Storage What lives where (Postgres, Durable Streams, Durable Objects).
Sprites API Programmatic sandbox control over HTTP and Node.
Observability Where logs, analytics, activation traces, and local control-plane state live.
Debugging CLI-first inspection flows for rooms, agents, streams, runs, and workers.
Development Local setup, env vars, deploy.
Deployment Workers, secrets, R2 bucket. How arbe gets shipped.
Releases CLI release contract: artifacts, download URLs, build, upload, versioning.
Design thinking
Thesis Every collaborative system independently approximates the same substrate. The divergence is accidental, not essential.
Primitives Records, streams, agents, permissions, mutations, signals. Six things — everything else is metaphor.
Layers Substrate, execution kernel, orchestration, adapters. What belongs where, and what already works.
Capabilities The right to cause side effects. Tools, resources, secrets, and why a capability without secret management is theatre.
Activation What wakes an agent. Automation is agent + activation policy + tools + permissions — no workflow DSL.
Memory Four kinds that shouldn't be conflated: working, durable semantic, observability, and world history.
Runs and sessions A run is executed work, not planned work. A session is a room with a short lifecycle. Results need durable identity.
Record types Concrete schemas for resources, tools, activation policies, artifacts, runs, memory, and secret bindings.
Sequencing Build order driven by the hourly Discord test. Wire one end-to-end path and let the types prove themselves.
What not to build No workflow DSL, no agent type hierarchy, no seventh primitive. The substrate test for evaluating additions.