The deploy model
A vertical you build on Substrat runs as a hosted app: one Durable Object per tenant scope, its own SQLite, served by code you pushed. This page is the model behind getting that code from your laptop into production and keeping it there safely — the concepts the deploy how-to and the dashboard both assume. The mechanics of the substrat CLI live in the how-to; the shape lives here.
Push vs deploy
Two distinct acts, deliberately not fused:
- A push submits a version. The CLI collects a source snapshot and POSTs it to the control plane; the platform installs (
pnpm install --frozen-lockfile), builds and bundles it, and records an immutable version (adeploymentRef, a permission digest, a migration digest). A push does not serve anything. Because the platform installs with pnpm alone, the snapshot needs a committedpnpm-lock.yamlat its root: the CLI refuses the push before uploading when there is none. A bundle that imports a Node builtin the worker's compatibility flags do not provide is refused, since workerd would refuse to start it: by the platform build on a push, and on your machine bysubstrat push --check, which builds the worker locally and runs the same check. - A promotion points a channel at a version and makes scopes run it. This is the deploy.
The split exists because "here is a new build" and "run this build against real data" are different decisions with different blast radii. A push is cheap and reversible — it just adds a version to the registry. A promotion changes what a live tenant sees.
Admission: may this code run here?
Before a version can be promoted it must be admitted — the answer to "may this code run on our infrastructure at all?" Admission is answered mechanically, by the sandbox contract: the bundle may declare only its own durable stores (a positive binding allowlist — no CONTROL_PLANE, no platform secret, and no binding whose name starts with SUBSTRAT_), it runs inside a Workers-for-Platforms isolate, and it is held to quotas. If the bundle satisfies the contract, nothing else is in question.
The SUBSTRAT_ refusal is by name prefix, whatever type the binding claims, and the reason admission gives is the whole rule: "the SUBSTRAT_ binding namespace is the platform's — these names are injected at deploy, never declared". A vertical that could declare SUBSTRAT_VERSION_ID itself would collide with the injected one — a duplicate name on the upload at best, a forged version stamp at worst — so the namespace is reserved as a whole, and a push whose declared bindings carry any SUBSTRAT_* name (a Durable Object namespace or a D1 store bound under it, or anything a future client declares) is refused with that message rather than admitted. Name your own bindings and config outside the prefix.
Reaching the outside world is not a binding — it is a granted capability. The allowlist deliberately excludes egress-shaped bindings (send_email, ai, browser, …): a hosted vertical never talks to a third party by declaring one. When a vertical genuinely needs a platform capability — sending transactional email, answering with a language model, provisioning tenants — it declares a request in its manifest (substrat.sendsEmail, substrat.usesModels, substrat.provisions) and something outside the bundle turns it on: a staff grant for email and provisioning (setVerticalEmailSender, setVerticalTenantProvisioner), a fleet-wide platform switch for models. The request is refreshed on every push, grants nothing by itself, and no push can set the flag it needs — but what that buys differs, and the difference is worth stating plainly. For email and provisioning the flag is per vertical, so a push can never acquire the capability at all. For models the switch is fleet-wide: a version that adds substrat.usesModels while the platform has models on does get the binding, and what a push cannot do is turn models on for a fleet that has them off. That declaration reaches a human at admission on a listed vertical; on a private one — auto-admitted, blast radius its own tenant — it is on the record rather than reviewed.
What the platform hands back differs by capability, and the difference is worth naming:
- A relay, for a capability that rides a credential. Email is the reference: the vertical POSTs to
POST /internal/email/sendon the control plane — the one worker holding an outbound-mail credential — which sends on its behalf and re-checks the grant on every call. The vertical holds no outbound credential and reaches no third party directly. - A real runtime binding, for models.
substrat.usesModelsis the one request answered with a binding instead of a relay: the uploader appends{ type: 'ai', name: 'AI' }to the script's bindings after the allowlist check has run on the declared set, so a vertical still cannot declareaifor itself — it can only be handed one. It takes both halves to appear: the platform willing to bind at all (a fleet kill-switch), and this version having asked. A vertical that never declared it gets no binding and falls back to whatever key its own env carries. The credential stays the platform's — the binding runs on the platform's own AI account, and nothing about it is in the bundle — but the honest bound is that a vertical holding it can callenv.AI.run()outside the metered path. - A version identity, on every deploy. The uploader also appends a
plain_textbinding namedSUBSTRAT_VERSION_ID, carrying the id of the version being served. Nothing has to be declared for it: it is the platform's stamp, not a requested capability, and it is what lets the scope host record which push wrote an event — theversionthatreadHistorysurfaces and the dimension the observability views group by. An in-place promote refreshes it to the version now being served rather than inheriting the outgoing one. Read it fromenv.SUBSTRAT_VERSION_IDif you need it; never declare it, or anything else under that prefix — admission refuses the namespace, as above. - The version's migrations, as a digest. When the platform holds the SQL migrations a push declared, both uploads also carry
SUBSTRAT_MIGRATIONS_DIGEST: one digest over the migrations your modules authored (the index and archive/trash migrations the platform derives from your declarations are left out). Before a scope applies a pending migration, the scope host compares it with the authored migrations the deployed code registers, and if they differ it applies nothing and fails that scope closed with amigration failed … scope fails closedrecord naming both digests. The fix is to push again from the build that is deployed. It is an integrity check: it catches a build whose worker registers other migrations than the push declared. A scope with nothing to apply is never checked, and a version pushed without its migrations in the manifest carries no digest and is not checked. - The same check, before upload. Where the platform can evaluate bundles, it does so on every push, in an isolate with no bindings and no network, and reads the migrations each scope class the worker entry exports registers. When the manifest carries migrations (an empty list counts: the bundle must then register none), a push whose migrations are not those is refused before anything is uploaded, and so is one whose worker entry cannot be evaluated without its bindings or does not settle: keep the entry free of import-time work, as the permission entry already is. If the platform's own reader fails, the push answers 503 and can simply be pushed again. A manifest that leaves its migrations off (over the size a manifest carries) is never refused on this account: what the bundle registers is recorded if it can be read, and nothing is compared. A version pushed before this is read at its promote, and the promote is refused if they differ; a version whose bundle cannot be read there is promoted as before and read again at every later promote. The promote review says whether the migrations it shows were read from the bundle or only declared by the push. This checks the build, not the code's intent: what is read is what the bundle registers when evaluated, so the apply-time check above stays.
Either way, "how a vertical gets a dependency" is: declare the request, get it granted, call what the platform hands over — never bind the raw resource yourself.
Who has to vouch for a version depends on who will be exposed to it (decision D-36):
- Private vertical (you own it, it is not listed on the marketplace). The only tenant that can run the code is the workspace that wrote it — you. There is no third party to protect, so the sandbox contract is the entire gate and a push lands admitted automatically. An auto-admission note records that no human vouched, so the platform can still tell an auto-admitted version from one a human reviewed.
- Listed vertical (published to the marketplace, so other tenants can install it against their data). Now a second question appears — "may other people run this code against their data?" — and that is a human decision. A listed vertical's pushes land pending for staff admission, and its production promotion is a staff decision too.
The human gate did not disappear; it moved to the boundary where it means something. The place a private vertical becomes listed — substrat publish, the setVerticalListed decision — is where a human vouches. Publishing is the checkpoint, not every push.
The one channel: prod
A vertical has exactly one channel — prod: the pointer at the version its scopes serve. There is no dev or staging. Those existed once and were write-only — nothing ever read or served them (#509) — because a channel names a pointer at code, and an immutable version id already does that. What a real non-production environment needs is not a second pointer but a second scope with data, which is a preview. The full argument, and how to run test / canary / release-candidate environments on previews, is Environments & previews.
prod stays a moving target — a promote re-points the prod scope at a new version — but it is a rebind, not a rename: the same scope, the same data, serving new code. For a vertical you own privately you self-serve it, so substrat push --promote prod is a complete deploy and a merge-to-main workflow can be the deploy. A prod promote re-points your live scopes in the same act — there are no other tenants who would be forced into lockstep (that concern, from decision D-30, is a shared vertical's many tenants, which a private vertical cannot have). For a shared vertical, that cascade is exactly why prod is a fleet-wide rebind, and why bringing one tenant forward first is a per-scope bind, not a channel.
Two things a promotion always respects:
- The surface checkpoint. A promotion whose permission or migration digest differs from what is live is refused until the diff is acknowledged, and the acknowledgement names the review it answers, so one given against a diff that has since moved is refused as stale (see an acknowledgement answers one review). This is the same two-human- checkpoint discipline the kernel applies to modules, applied at the deploy boundary — with the owner as the human at their own checkpoint.
- Channel history. Every promotion appends a row: what went live, what it replaced, who did it, and exactly when. That history is the dashboard's rollback picker, and each timestamp is the instant a point-in-time rewind would restore the data to.
In-place updates: data carries forward
The property that makes "promote prod from a laptop" safe is that a vertical serves in place (decision D-37). A version update is not a rebind to fresh, empty storage:
- A prod promote re-uploads the promoted bundle onto the vertical's one stable serving script. The scope's Durable Object and its SQLite stay put — data does not move.
- Because the data is still there, the kernel's append-only migrations run forward against production data, exactly as designed. This is the mechanism the whole migration model is built around; before in-place serving it never actually ran in production.
- Secrets survive the deploy.
- A promote repairs its own installs. Each scope records the version its provision hook last ran against (
provisionedVersionId), and once a scope is bound to a new version — by a promote or a per-scope bind, never by an upload alone — the platform sweep re-runs/internal/reconcileon every active install whose receipt is behind the version it now serves, or whose reconcile did not finish that version's retirements. So whatever a new release'sonProvisionmints reaches existing installs too, which is why that hook must be idempotent. The how-to is in Deploying a vertical.
A version is badged code-only or schema-change at publish, so you know whether a promote touches the schema. A code-only update just re-points; a schema-change update runs migrations, so it wants its migration diff acknowledged first.
A migration cannot quietly lose data
Migrations run forward against production data, so the kernel refuses one that would lose some of it. Before and after each migration you wrote, inside the same transaction, it counts what the scope holds: rows per table, and values per column, by storage class. A migration made only of CREATE … and ALTER TABLE … ADD … is not counted, because it cannot remove anything. Any other migration is refused if it leaves a table that held rows gone or with fewer rows, or a column that held values gone, holding fewer values, or holding them as a different type ('1.50' turned into 1). Renames (ALTER TABLE … RENAME TO, RENAME COLUMN) are followed, and so is the usual create-copy-drop-rename rebuild. A table that holds nothing yet can be dropped or reshaped freely: before there is data, there is nothing to protect.
A refused migration rolls back whole. The scope fails closed, exactly as it does for any failed migration, with its data where it was. You recover by promoting the previous version back (the migration never ran, so the old code still fits the schema) or by shipping a fixed one.
When losing or moving data is the point, say so on the migration, beside its SQL, where the migration diff is reviewed:
{
version: '0007-retire-drafts',
sql: `INSERT INTO notes (id, body, written_by) SELECT id, body, author FROM drafts;
DROP TABLE drafts;
ALTER TABLE notes DROP COLUMN legacy_flag;`,
// Verified: `notes` gains every row `drafts` held, and each of drafts' columns arrives in a
// `notes` column of the same name (`id`, `body`) or is moved by name (`author`).
moves: { drafts: 'notes', 'drafts.author': 'notes.written_by' },
// Given up on purpose. The reason is required; it is what the reviewer reads.
discards: { 'notes.legacy_flag': 'the flag was never read after the 0004 redesign' },
}A move goes table to table or table.column to table.column, and it is checked: if the target gains less than its sources held, the migration is still refused. A table moved whole must also bring each of its columns that held values, into a target column of the same name; a column that arrives under another name is moved by name, and one left behind is discarded by name, or the migration is refused. A declaration that names a table or column the scope does not hold is refused as a typo. Migrations the model planner generates never need either: it refuses to write a destructive change in the first place.
The check counts values; it does not compare them. So it reports any change of a value's storage type, including a faithful widening (5 becoming 5.0 when a column moves to REAL), because a count cannot tell that from 5 becoming 0.05: a widening you mean is declared with discards, naming the column and saying what changed. And it cannot see values rewritten in place at the same count and type, rows replaced by as many other rows, or a column dropped, re-added and refilled. Nor a table dropped and its name then taken by a new table holding at least as many rows, filled from somewhere else (DROP TABLE a; CREATE TABLE a AS SELECT * FROM b), even if that new table is renamed again afterwards: that looks exactly like a rebuild, or a rebuild and a rename. Nor which source a move's target gained from. In the other direction, data copied under another table's name is refused until moves declares it.
A migration that creates a TEMP table, view, index or trigger is refused before it runs. A Durable Object does not allow TEMP objects, so it could never run in production; use a regular table and drop it before the migration ends. So is one that runs ATTACH or DETACH, for the same reason: a Durable Object refuses both, and an attached database is a file outside the scope.
substrat push asks the same question before it uploads anything. It replays your migrations, in the order a scope applies them, against an in-memory scope where every table holds a row and every column a value, through the fence in your @substrat-run/kernel, the copy your scopes run at promote. A migration that would lose undeclared data refuses the push, with the same message and the declaration to add. substrat push --check runs it too, so a CI job that gates on --check fails in the pull request. The replay runs in a process of its own, with an empty environment, against an empty in-memory database. It reads none of your data, and since ATTACH is refused it writes no file. Each migration gets 30 seconds: one that runs longer, such as a recursive CTE with no end, is stopped and reported as incomplete. A Durable Object's own CPU limit would stop it at promote too. The replay process also ends with the push, however the push ends: on exit, on Ctrl-C, or killed by any signal, SIGKILL included. A watchdog thread inside it notices the push is gone within a fraction of a second. The one case it cannot see is a push that is paused (SIGSTOP) rather than gone; the replay then stops at its own overall deadline. The watchdog relies on how POSIX systems re-parent an orphaned process, so on Windows only that deadline stops a replay whose push was killed.
The replay needs node:sqlite, so Node 22.13 or later. If a migration reads one of the platform's _substrat_* tables, it also needs @substrat-run/adapter-sqlite installed, at least as a devDependency, to build them. When it cannot run, the push still goes ahead and says so loudly. That happens when SQLite is unavailable, when your kernel predates the replay, or when a migration's SQL cannot run on made-up values (a json_extract over text that is not JSON) or in time. The summary line reads data-loss check: SKIPPED (…), or INCOMPLETE (3 of 7 authored migration(s) were not replayed after …), because the replay stops at the first migration it cannot run. That default is permissive on purpose, because promote is the hard gate: the fence still refuses there. To make a skipped or incomplete check refuse the push as well, pass --require-data-loss-check, or set SUBSTRAT_REQUIRE_DATA_LOSS_CHECK to 1, true or yes in CI. Any other value is read as no, with a warning. There is no flag past a refusal. A discards entry with its reason is how a migration loses data on purpose, including a table you know is empty everywhere, which the replay fills like any other.
In this repository pnpm lint:migration-fence runs the same replay over every migration, so an undeclared loss fails in the pull request that adds it.
The declarations also travel with the version. substrat push carries each migration's moves and discards beside its SQL, and the promote review (the dashboard's promote dialog and substrat promote) lists them under the migration: every move as source → target, every discard with its reason word for word. A promote that discards anything says so first, and says "at least" when the list is cut. Everything the review shows from the version (the reason, the table and column names, the migration's id and its SQL) is the author's own text, so it is shown as plain text with every control, format and bidirectional character made visible as <U+XXXX>: an escape sequence cannot drive your terminal, and a reason cannot reorder, hide or forge what you read. A long reason, or one of many lines, is cut behind a "show all". A version pushed before declarations were carried, or a migration that declares none, shows none.
A reason has to say something a reviewer can read: one of only whitespace or invisible characters is refused, by the same rule at the push and when the migration runs. A declaration cannot name __proto__, refused at both too; constructor and prototype are ordinary table names. A migration's id and version are shown on one line, with a newline or tab in them made visible too, so neither can start a line of its own in the review.
Declarations are not part of the SQL, so they do not change the digest a scope journals for the migration, and editing one on a shipped migration does not make a scope that already ran it fail closed. They are part of the version's migration digest, so a promote that adds, removes or rewords a declaration asks for the migration acknowledgement like a SQL change does. The control plane derives that digest itself from the migrations the push declares, which it stores, and refuses a push whose own digest is another one before anything is uploaded. What the review shows is read from the declarations the control plane stored, never inferred from the digest, so a client that hashed something else cannot hide a declared discard from the review.
Previews: run a version against a copy of the data
Before a promotion whose migrations changed, you often want to see the new version run against real-shaped data without touching production. Substrat can do this because the scope-host contract already runs identical module code on two adapters — so a preview is a fork of a scope's data bound to the new version, reachable at its own URL.
The governing law is that migrations are forward-only: a snapshot taken today (at prod's migration frontier) bound to today's or a later version rolls its migrations forward on the copy — rehearse the new version against real-shaped data, throw the fork away if it breaks, and prod never saw it. The inverse — pointing old code at today's data across a schema change — is invalid, because you cannot un-run a migration. So the rollback strategy is fork-before-you-promote: snapshot right before binding the new version, and a bad version leaves the prior one still runnable at its correct frontier. A fork is a governed dead end — the export copies the kernel spine too, so no connector, cron, or billing consumes from a preview — and preview URLs are non-public, gated code running against real-shaped data. The everyday shape of all this — test copies, fearless upgrades, real data pulled to a laptop — is snapshots & test copies.
Backup, restore, and backout
Because every app is one scope with its own database, recovery is a per-tenant primitive, not an environment-wide runbook — one tenant's rewind is a clean, self-contained blast radius.
- PITR rewind — the first-hours backout. Right before an upgrade migrates, the scope DO bookmarks the instant (Durable-Object point-in-time recovery, ~30 days of history). If a promotion goes wrong, an audited rewind rolls the scope's data back to that bookmark, time-boxed to ~24h unless forced. A rewind is a destructive, in-place rollback of that one DO — the opposite lever to a fork, which is a non-destructive copy. It rewinds the whole database, so a stale bookmark is refused rather than silently skipped. One sharp edge: data and version binding live in different DOs, so rewinding past a bad migration means also rebinding the version — two coordinated rewinds, no atomicity between them.
- Backup / restore — the considered path.
substrat scope restoreloads a backup into an existing hosted scope, replacing its data — a pulled.sqlite, a local adapter-sqlite scope file, or a dump. This is the deliberate recovery when a time-boxed rewind is not the right tool. - Legacy adoption. A scope that predates the stable serving script hops onto it once with
adopt-serving(export → restore → flip, data-first), so future promotes stop stranding its data. A cross-lineagescope rebindmoves the data the same way. In both, the copy left in the old script is deleted once the move is confirmed: it is not a backout. To keep a way back, take a snapshot or backup of the scope first and restore from that. An old copy that took a write after the move read it is kept for review instead of deleted.
The whole shape
Push uploads a version; admission asks may this run here (automatic when you are the only tenant exposed, staff when you list it); promotion points a channel and serves in place so data carries forward across every update; previews rehearse a risky version against a fork of real data; and PITR rewind plus backup/restore are the backout. The staff human gate lives at publish — the moment other tenants can run your code against their data — and nowhere else in the loop.
See also: Deploying a vertical (the how-to), Snapshots & test copies, and The platform layer.