Backend Modules

BoxHaven can add private or deployment-specific behavior at build time through the BackendModule interface exported by @boxhaven/backend. The standard open-source entrypoint loads no modules and uses the in-process allow-all commercial policy.

A module can contribute ordered SQLite migrations, authenticated API routes, a CommercialPolicy implementation, and a provider-neutral TeamDeletionPolicy. It receives the core database, provider registry, state store, authentication helpers, and team authorization helpers in process. This keeps provisioning, auth, SSH, and lifecycle behavior in the open core while allowing a distribution to add its own models and UI.

Database Ownership

Every module migration has a stable integer version. The backend applies core and module migrations before listening and records them in the shared boxhaven_migrations table. It refuses duplicate module names, missing versions, migration downgrades, and changed migration history.

Use a prefix unique to the module for every private table and index. A module must not modify tables owned by the core or another module. The backend process is the sole owner of the SQLite connection and closes module runtimes before closing core storage.

Commercial Policy

A module can return a CommercialPolicy from start(). The policy can:

• authorize a create before provisioning;
• receive idempotent machine.created, machine.destroyed, and machine.moved lifecycle facts;
• reconcile against the authoritative active-machine set;
• request provider-neutral destruction of machines whose entitlement has ended;
• provide an account summary and account action to its own routes or UI.

The complete lifecycle event is written to the shared SQLite database in the same transaction as the machine mutation. Delivery happens asynchronously; failures remain in the durable outbox and retry after restarts. Stable event IDs make duplicate delivery safe.

Reconciliation may return machine.destroy actions keyed by authoritative team ID and stable policy machine ID. Core persists each accepted request before contacting the machine's provider. Provider deletion is retried across reconciliation runs and process restarts, and a failure for one machine or provider does not stop other pending cleanups. Core removes the machine and emits its final machine.destroyed fact only after the provider confirms the resource is absent. Duplicate actions and concurrent policy runs converge on the same pending cleanup.

Once cleanup is pending, a machine cannot be renamed or moved to another team. A concurrent user-requested destroy may complete the same cleanup; the state transaction emits only one destroyed fact. Policies should return actions in a deterministic order and continue returning them while the corresponding machine remains in reconciliation. Core also retains accepted requests, so a restart does not depend on the policy returning the action again.

If a policy throws or returns an invalid create decision, BoxHaven returns 503 entitlement_unavailable and does not provision the box. An explicit denial returns 403 entitlement_denied. Listing, connecting, running, syncing, moving, and destroying existing boxes do not wait for policy delivery.

The generic policy timing settings also control cleanup retries and fresh entitlement evaluation: BOXHAVEN_COMMERCIAL_POLICY_RETRY_MS defaults to 30 seconds and BOXHAVEN_COMMERCIAL_POLICY_RECONCILE_INTERVAL_MS defaults to five minutes. A module can call requestPolicyReconciliation() after an external entitlement event to request an immediate serialized run.

Deletion Policy

A module can return teamDeletionPolicy.checkTeamDeletion. The input contains only the team and requesting actor; the decision is an allow flag and optional actionable message. The core has no knowledge of why a module blocks deletion.

Team deletion always fails closed while a core box or provisioning reservation exists. Each process-owned provisioning reservation is paired atomically with a durable machine record. After a restart, core clears the stale reservation and marks that record as requiring recovery; the record continues to block team and account deletion until the box is explicitly destroyed. Recovery records are not provider-confirmed lifecycle facts and are excluded from commercial-policy reconciliation, so a crash cannot activate billing by itself. Provider discovery can fill in VM identity and address details for cleanup, but it never promotes a recovery record into a usable or billable machine. The box must be destroyed and created again. A provider may classify an error as definitively not created; only then does core remove the placeholder automatically. Unknown outcomes keep the recovery record.

Modules whose external state can change concurrently also maintain a row in the generic core_team_deletion_policy_blockers table in the same transaction as that state. The core checks those rows before deletion and a SQLite trigger checks them again inside Better Auth's organization-delete transaction. This prevents a late external-state transition from racing a successful delete. Do not put provider-specific credentials or payloads in the blocker row; its message is user-facing and retained only until the blocker is cleared.

Building A Distribution

Import startBackendFromEnv and pass modules explicitly from a distribution's entrypoint:

import { startBackendFromEnv } from "@boxhaven/backend";
import { hostedModule } from "./hosted-module.js";

await startBackendFromEnv({ modules: [hostedModule] });

The standard @boxhaven/backend entrypoint always starts with zero modules. There is no environment variable that enables private functionality in the open-source image.