opbox

Migration / Provisioning

Stand a tenant's box up from Postgres, and move work onto it one matter-type at a time, with a cutover gate and rollback at every step.

Opbox runs one box per client (ADR-0004): a single organisation’s substrate, kernel, agents, and front door, all co-located on its own server. Migration and provisioning is the machinery that brings that box into being and moves real work onto it. Provisioning materialises the box from a single source of truth in Postgres rather than from a pile of config files, and migration moves a firm off its old system the careful way: one matter-type at a time, each behind a cutover gate, each able to roll back. This is operator work. Almost every verb here is Owner-tier and out of the AI’s reach.

What it does

Reconcile a box from the truth in Postgres. The roster - the agents, their roles, who reports to whom, their SOUL specs and delegations - lives as rows in Postgres, not as a roster file on a volume (ADR-0011). Provisioning is one idempotent action that materialises the running box from those rows: it seeds the org root, brings up the kernel and agent runtime, opens the front door, and binds each seat’s key. Because it reconciles from the truth rather than applying a script of deltas, you can re-run it and converge to the same state, and a box can rebuild itself after a reboot without hand-patching. The isolation boundary is the host itself, so a client’s regulated data never shares a box with another tenant’s.

Set up a vertical from a blueprint. A vertical (the visa line of work, the company-secretarial line) ships as a setup bundle: the templates, knowledge, verb-pack configuration, and policies that a line of work needs, expressed as configuration over the shared primitives, never as new substrate code. You define a bundle, publish a version of it, and adopt that pinned version onto a box. The live org is then reconciled from the manifest’s pinned versions, so the box ends up exactly as the bundle describes. A bundle can be diffed before it is applied, rolled back, and exported or imported as a portable dump, so the same setup can be carried cleanly from one box to another.

Migrate one matter-type at a time, not all at once. The migration model is a strangler, not a big-bang. The new box runs alongside the firm’s current system, and you move work across one matter-type at a time. Each matter-type carries its own migration state as it crosses: provisioned, shadowing the old system, then live on Opbox. The flip from one state to the next is operator-driven and sits behind a cutover gate with a per-step rollback, so a move that does not settle can be unwound rather than fought. Document rendering tends to move first, then forms and intake, then billing.

See every matter-type’s migration state on one dashboard. While a firm is mid-migration, the operator needs to see where each matter-type stands across the whole box. The coexistence dashboard reads exactly that: for one matter-type, its migration state, its soak-window end, whether rollback is still armed, and where its data sits; and across the box, the full roster of matter-types with their states and gate-readiness. These reads are a projection over the audit log and the matter-type’s own rows, computed live, never a second store that could drift. As cutover events happen, the box raises a migration notification.

Run the box: suspend, resume, upgrade, back up, restore, tear down. Once a box is live, the same operator front door runs it. You can deploy and upgrade it, suspend it and resume it, take scheduled encrypted off-box backups and restore from them, export the full domain as a portable serialisation, and, at the end of its life, deprovision it (archived or purged). A restore is data-first then reconcile-from-Postgres, and it fails closed if the audit chain does not verify, so a recovered box is provably the box it claims to be rather than an unverifiable copy.

Kept out of the AI’s reach. Provisioning, migration, backup, restore, and teardown are Owner-tier operator actions. They fail closed for an agent: the substrate runs the box, but the box’s own machinery is driven by a human operator, never offered to the AI workforce. See Security and permissions for how the front door enforces that.

How you use it

Stand a box up. Provision the tenant from its Postgres roster: the reconcile brings up the org root, the kernel, the agent runtime, and the front door in one idempotent pass. Re-run it whenever you need the box to converge back to the truth.

Install a vertical. Publish the bundle for the line of work, adopt the pinned version onto the box, and apply it so the live org reconciles from the manifest. Diff first if you want to see what the apply will change before you commit to it.

Migrate a matter-type. With the new box running alongside the old system, move one matter-type across: author and adopt its bundle, let it shadow, then drive the operator flip through its cutover gate. Watch its soak window, and keep rollback armed until you are sure it has settled.

Watch the migration. Open the coexistence dashboard to read where every matter-type stands - its state, its soak-window end, and its gate-readiness - so you always know what has crossed, what is shadowing, and what is still on the old system.

Run and recover the box. Check the box’s runtime and health, set its backup cadence and disaster-recovery policy, take and verify backups, and, if you ever need to, restore from a backup (data first, then reconcile, with the audit chain verified) or export the whole domain to carry it elsewhere.

The kernel verbs behind it

Everything above runs through the kernel’s one front door: each call is permission-checked, scope-checked, and audited before it executes. These verbs are operator-side and Owner-tier; they fail closed for an agent.

Migration and cutover:

  • migration.status - read one matter-type’s migration state, soak-window end, rollback-armed flag, and box placement.
  • cutover.list - the box-wide roster of matter-types with their migration state and gate-readiness, the surface the operator drives the strangler from.

Provisioning a box and its verticals:

Running the box:

See the full set in the tenant verb reference and the setup verb reference.