opbox

Kernel / Ops Meta-Feature

The one front door every action passes through, and the operator-side machinery that runs each tenant's box - deploy, back up, restore, and keep it healthy.

Two things sit underneath everything else Opbox does. The first is the kernel: the single Rust front door that every action, from every surface, passes through to be permission-checked and recorded before it runs. The second is the operator-side machinery that runs the box itself: provisioning a tenant, backing it up, restoring it, rotating its secrets, and watching its health. Neither was a feature in legacy Opbox, where each surface built its own backend and the box was set up by hand. In v2 they are first-class, named, and governed by the same primitives as the rest of the product.

What it does

One front door for every call. Whether an action comes from chat, a button in the app, or a script on the command line, it enters through the same single entrance: a POST /v/:verb dispatch over one verb registry and one connection pool. There is no second backend and no privileged side-channel. Before any database work happens, the dispatch gate resolves the caller’s authority tier, autonomy level, and capability scope, and it appends exactly one hash-chained audit event in the same transaction. That is what lets the AI be handed real work safely: it enters the same way a person does, under the same checks, and leaves the same trail. See the kernel for the full model.

Tiered capability, never feature flags. Every verb is registered once with its required tier and risk, and least-privilege is computed from the caller’s standing rather than a paywall. The everyday verbs are always on hand; the operator-side ones described here are AdminOnly: real, working capability reachable by an authorised person, deliberately kept out of the assistant’s reach. A bounded agent simply cannot dispatch them, no matter what its scope says.

Provisioning and the tenant lifecycle. Each client runs on its own box, and the kernel drives that box through its whole life. You deploy a tenant, suspend it, resume it, and upgrade it in place, each as a governed, audited transition. Tearing one down is the one state-destroying move and is its own destructive verb, so a box is never wound up by accident or off the record.

Backup, restore, and disaster recovery. A tenant takes scheduled, encrypted, off-box captures (the Postgres base plus write-ahead log, blobs, the org roster, and the audit chain), with the cadence, retention, destination, and data residency set as policy. Restore runs data-first and then reconciles the running system from Postgres, and it verifies the audit chain on the way in: a restore with a broken chain fails rather than bringing back a tampered record. Alongside it, you set a disaster-recovery policy (the recovery objectives and how often a restore drill must run) and read back the current recovery status.

Setup blueprints a box can adopt. A tenant’s shape - its verticals, templates, roster, and policies - is captured as a setup bundle that can be defined, published, and then adopted onto another box. Applying a bundle reconciles the live org from the manifest’s pinned versions rather than mutating it blindly, and a bundle can be exported, re-imported as a draft elsewhere, diffed against what is live, or rolled back. A box that has already adopted a version keeps it even if that version is later withdrawn, so an in-flight setup never shifts underneath the work.

Secrets, credentials, and connections. Box-local secrets (the database role, the app role, signing keys, LLM keys) rotate through a single governed verb. Stored credentials are inventoried masked (the secret is never returned), verified with a dry run, rotated in place, capped per key, and terminally revoked. Connections to outside systems are authored with their credentials encrypted at rest, checked for reachability, enabled or disabled, and removed with an explicit decision about the data they synced. The HMAC keys that pseudonymise party identifiers can be rotated wholesale by re-hashing every identifier to the new key version in one pass, with no multi-version window.

Egress as a tightenable floor. Outbound rails carry a maximum data classification, and the egress policy can only be tightened from the substrate’s default, never loosened below it. Regulated data is never allowed out by default. The egress chokepoint runs as part of the same front-door gate, before any handler becomes load-bearing, so the policy is enforced on every call rather than bolted on at the edge.

Health, host, and migration visibility. A live GET /health probe answers liveness with no version disclosure, and system.health exposes the same check as a governed verb. The host doctor returns a machine-readable snapshot of services, tenants, storage, and preflight state for unprivileged discovery. When a line of work is being moved onto Opbox, the migration and cutover reads project from the audit log rather than any new store: where each matter-type sits in its journey, its soak window, whether rollback is still armed, and its gate-readiness across the box.

How you use it

Stand up or wind down a box. Deploy a tenant to bring its box online, then suspend, resume, or upgrade it as the engagement requires. When a tenant is finished, deprovision it: archive it to a tarball, or purge it outright. Each transition is a named verb, owner-gated, and on the record.

Protect the data. Configure the backup cadence, retention, destination, and residency, then let scheduled encrypted captures run off-box. When you need to recover, restore from a point in time and let the system reconcile from Postgres and verify the audit chain before it trusts the result. Set your recovery objectives and drill cadence as a disaster-recovery policy, and read the recovery status when you want to know where you stand.

Carry a setup between boxes. Define a setup bundle for a vertical, publish it, and adopt it onto a new tenant. Export an existing tenant’s setup, import it as a draft elsewhere, diff it against what is running, and roll back a change that did not land cleanly.

Keep credentials clean. List the stored credentials (masked), verify one with a dry run, rotate or revoke it, and set a per-key spend cap. Rotate a box-local secret on a schedule or after an incident, and re-hash the identity keys when you rotate the HMAC secret. Author and check a connection to an outside system, and disable or delete it when it is no longer wanted.

Check on the box. Run the host doctor for a snapshot of services, tenants, storage, and preflight, hit the health probe for a fast liveness answer, and read the migration and cutover views to track a line of work being moved onto Opbox.

The kernel verbs behind it

Everything above runs through the kernel’s one front door: each call is permission-checked and audited before it executes, and the operator-side verbs are AdminOnly, never offered to the assistant. These are the key kernel and ops verbs.

Provisioning and lifecycle:

Backup, restore, and DR:

  • tenant.backup - a scheduled encrypted off-box capture (Postgres base and WAL, blobs, roster, audit chain).
  • tenant.backup.configure - set backup cadence, retention, destination, and residency.
  • tenant.backup.status - read the backup state.
  • tenant.restore - point-in-time restore, reconcile from Postgres, then verify the chain (fails if the chain is broken).
  • tenant.export - a full-domain portable serialisation of the tenant.
  • dr.policy.set - set the recovery objectives and restore-drill cadence.
  • dr.status - read the current disaster-recovery status.

Setup blueprints:

Secrets, credentials, connections, and egress:

Health and migration visibility:

  • system.health - the live health probe as a governed verb.
  • host.doctor - a machine-readable host snapshot: services, tenants, storage, preflight.
  • config.get / config.set - read and write box configuration.
  • migration.status - read one matter-type’s migration state, soak window, and rollback-armed flag.
  • cutover.list - list every matter-type’s migration state and gate-readiness across the box.

Because they all share the one front door, an action run by an operator and an action run by an agent obey exactly the same checks and leave exactly the same audit trail. See Security and permissions for how the front door governs every call.