opbox

The kernel

The Rust verb kernel — the trust boundary, the verb model, and the three doors over one dispatch.

The kernel is the only substantial code Opbox owns and the system’s trust boundary. It is a single Rust binary that is both the opbox CLI and the HTTP/MCP server. Every capability is a verb; nothing reaches the data except through a verb.

The front door

The axum router exposes a small, fixed surface:

RoutePurposeAuth
POST /v/:verbDispatch a verb (the raw JSON body is the input)Bearer
POST /mcpThe Streamable-HTTP MCP transport (the caged agent’s door)Bearer
POST /auth/loginEmail + password → a SESSION tokennone (bootstrap)
POST /auth/reset/*Password resetnone (bootstrap)
GET /healthUnauthenticated liveness ({"status":"ok"}, no version disclosure)none

All three doors (CLI, HTTP, MCP) dispatch through the same registry and the same pool — there is no second backend (INV-14).

One door, no exceptions

The agent, the CLI, and the web app all enter the same way: one verb, permission-checked and audited before it runs. There is no privileged side-channel - which is why the agent can be handed real work safely.

Token-only in release

A release binary is built with the dev-identity cargo feature dropped (ADR-0040), so the only way to resolve an identity is a bearer token. A production server cannot fall back to a privileged dev actor — it is a compile-time fail-closed property. The bootstrap ceremony (opbox initiate) mints the first owner bearer; see Genesis.

The verb model

There are ~360 verbs across ~40 noun domains (matter, form, doc, board, bill, party, signing, org, token, gate, review, trigger, and more), spread over four tiers - about 68 are always-on Core, the rest unlock on demand or are admin-only (see Capabilities). Each verb is registered once with its metadata, and the dispatch gate checks all of it before any database work (fail-closed, INV-11):

  • Authz tier — the caller’s standing must meet the verb’s required tier (MEMBER → ADMIN → OWNER, or EXTERNAL for provider/portal surfaces).
  • Autonomy level — the caller’s per-request autonomy (min(actor, token ceiling), 0–3) must meet the verb’s implied level. Level 0 is read-only; sensitive and owner operations need higher levels.
  • Capability scope — if the bearer carries a verb allow-list, the verb must be on it (the narrowest, per-bearer fence).

This is why least-privilege is tier + autonomy + scope, never a feature flag (INV-12). A bounded agent at autonomy 1 can read and create matters but cannot perform sensitive or owner operations, regardless of its verb scope.

The data plane

Postgres + pgvector is the single source of record. The kernel writes through one path per fact (INV-1) and appends exactly one hash-chained audit event per verb call, in the same transaction (INV-8). The append-only event log makes every action tamper-evident and attributable.

Idempotency

A retried POST /v/:verb carrying the same Idempotency-Key header returns the first call’s response instead of re-executing — so a durable orchestrator (see Hatchet) can retry safely. The dedup is keyed (workspace, key) and is additive: with no header, the dispatch path is byte-identical.