Skip to content

create-substrat ​

The initializer — scaffolds a vertical that installs, runs, and already carries the rules your AI editor needs.

sh
npm create substrat <dir>
npm create substrat .        # scaffold into the current directory

Getting started builds the smallest real thing by hand, package by package, to show what the pieces are. This is the other entry point: the full project shape in one command, for when you want to build an actual vertical rather than learn the layers.

What it writes ​

The vertical skeleton — a working bike shop, laid out the way the linter and tests expect:

src/entities.ts        defineEntities — what exists
src/operations.ts      defineOperations — the declared surface (input, output, permission, http)
src/manifest.ts        the module manifest + permission and env constants
src/migrations.ts      the append-only SqlMigration[] journal
src/model.ts           the emitted model, the artifact of record
src/module.ts          the handler bodies, bound to the declaration
src/provision.ts       MODULES, ROLES, grant shapes — what `substrat push` reads
src/seed.ts            a world to develop against
src/personas.ts        the local dev cast, read by the dev issuer and the seed
src/routes.ts          the HTTP API, DERIVED from the operations — it holds no table
src/server.ts          the Node dev server (SQLite adapter, OIDC against the dev issuer)
src/worker.ts          the deployable Cloudflare worker
spec/concept.md        the design document you approve before any code; `substrat concept sync` writes its generated sections
test/scenario.test.ts  the scenario, including the denials
test/entities.test.ts  the entity registry held to the tables its migrations create
test/invoke-route.test.ts  the hand-written /api/invoke route, held to the platform's one door
test/portal-shape.test.ts  the portal's entity-narrowed reads
test/setup.ts          the 50-byte LIKE/GLOB pattern limit, on by default (vitest setupFiles)
test/sql-limits.test.ts  proves the setupFiles wiring itself — goes red if setup.ts stops running

src/operations.ts is where an operation is declared; src/module.ts holds only its body. src/routes.ts derives every operation route from the http each operation declares, through mountOperations from @substrat-run/vertical-host, and both server.ts and worker.ts mount that one derivation — so a new operation route is a declaration on its operation, never a handler added to one entrypoint. Two kinds of route stay hand-written and are meant to: the generic POST /api/invoke transport routes.ts registers above the derived table, which keeps an operation that declares no http of its own reachable on both hosts; and each entrypoint's own auth-shaped routes, which answer "who am I on THIS host" and cannot be shared — /api/auth/* and /api/me in server.ts, and in worker.ts the ones workerDoor mounts (below). The permission keys defineOperations takes are the same array src/provision.ts hands definePermissions({ …, keys }), which throws at module load when those keys and MODULES disagree. Agent rules is the same layout, emitted from the AGENTS.md the scaffolder writes.

The instruction layer — AGENTS.md (the rules) and .substrat/playbook.md (the build flow), plus a command stub per tool so Claude Code, Cursor and opencode all read the same two files (Claude Code's CLAUDE.md is a one-line import of AGENTS.md). A session-start hook points the agent at the docs matching the kernel version installed. This is the point of the scaffolder: the skeleton is small, but an agent that already knows the three-layer rule and the module-code rules is what makes the next hour productive.

The generated configs — package.json, tsconfig.json, vitest.config.ts, .gitignore and a project README.md. The package.json carries the substrat block that substrat push reads — the permission surface it diffs at the promotion checkpoint, and the runtime needs it derives deploy config from. You never author wrangler config.

Then the agent builds ​

sh
cd <dir> && pnpm install

Open the project in your AI editor and start the flow — /substrat in Claude Code, the new-vertical command in Cursor or opencode. See building for AI agents for what that loop looks like and why the rules live in the repo rather than in a prompt.

Signing in locally ​

sh
pnpm dev

starts two processes: @substrat-run/dev-issuer on :8879 and the Node dev server (src/server.ts) on :8891. The issuer is a real OpenID Connect provider whose only shortcut is that /authorize lists the people in src/personas.ts instead of asking for a password; the dev server is an ordinary relying party against whatever OIDC_ISSUER names (http://localhost:8879 by default). Open http://localhost:8891/api/auth/login, pick a name, and you are signed in through the same round-trip a deployment runs — the seed links each persona's sub to a principal in the identity directory, so the vertical never learns who you are from anything but a verified token. There is no dev header and no dev auth branch: pointing the project at Auth0, Keycloak or your own issuer is a change of OIDC_ISSUER, not of code. A script that needs to act as someone mints a bearer at the issuer instead — curl -XPOST localhost:8879/dev/token -d '{"sub":"dev|greta"}'.

The worker carries the same sign-in. src/worker.ts — what substrat push deploys — composes workerDoor from @substrat-run/vertical-host/worker-door, so a hosted install answers a signed-in request without any auth code of yours. It supplies what is the worker's own: the AUTH binding (the tenant's identity directory), how a request routes to a (tenant, scope), hostFor, and the vertical's envSpec. The worker exports IdentityDO, the Durable Object behind AUTH, because workerd resolves a DO class from the entry module's exports; it is declared as a store in substrat.runtimeNeeds.stores beside SCOPE and SWEEPER. door.mount(app) then adds the login round-trip at /api/auth/*, who is signed in at /api/me, and the owner seat at /api/claim-owner, and door.scope(c) hands a route the caller's scope stub — 401 when nobody is signed in. The issuer is the one the dashboard delivers for the install (substrat:auth, read through @substrat-run/vertical-auth's instanceAuthFor); the worker holds no credential store and no dev header. door.platform fills the provision, configure and delete hooks of mountPlatformSurface, including seating the first owner.

Member invites go through the door too. A person a member invite names is admitted by the address their issuer verified, with no link: the first time they sign in, the door finds the open invite naming that address, binds them to its principal, and they arrive with its role. Name your invites and the door mounts POST /api/member-invites ({ email, roleKey }) and POST /api/member-invites/:principal/withdraw. It sets up the platform's half first, bounded by the inviter's own role, then runs your operation as the inviter: who may invite is your rule, and the mail it queues says "sign in with this address". If your operation refuses, the invite is withdrawn. An address has one open invite at a time (a second is 409). A withdrawal runs your cancel operation first, as the caller, then takes the platform's half, so it must succeed for an invite it already withdrew, as a join returns the row it already wrote. src/server.ts does the same locally: its devMemberInvites admits an invited person when they sign in, and members.mount takes the same invites the worker names. To hand out links instead, add mountInviteRoutes from @substrat-run/vertical-auth behind your own admin gate; a link naming an address opens only for a verified holder of it.

The worker's first registration is the invocation log, and it must stay first:

ts
app.use('*', invocationLog<Env>({
  routerSecret: (env) => env.ROUTER_SECRET,
  allowUnsigned: (env) => env.ALLOW_DEV_NODE === 'true',
}));

A deployed script is stamped by the platform as well: the upload puts an entry of its own in front of the worker, wrapping it in the same stamp, and this middleware then steps aside rather than writing a second line. It stays in the template because it is the explicit, visible form of the stamp, and it is what places the stamp before your routes wherever the app runs.

invocationLog from @substrat-run/vertical-host writes one line per routed invocation, stamped with the tenant and scope the router asserted. An invocation whose assertion it cannot accept — an un-routed local request, a missing, malformed or unverifiable one — emits no line at all, deliberately: a line with no tenant is one nothing may show a tenant, and inventing one is the only way this could leak. So an empty local log is the contract working, not a fault to chase. Cloudflare keys observability on the worker script, and one script serves every tenant that installed the vertical, so this line is the only thing that files your invocations under the tenant they served — without it the app's Observability page stays empty and says nothing about why. It must come before every route because Hono runs handlers in registration order and stops at the one that answers, so a route registered above it is never logged. On the deployed path the stamp is taken from the verified router assertion (routerSecret), never from the header — the same verification the vertical's own nodeFor does, with the same secret, and a failed one writes nothing. allowUnsigned is the local-only exception to that, and the two knobs must be given the same answers here as in nodeFor: it accepts the x-substrat-* headers unverified so an un-routed dev instance still logs, which anywhere a secret is configured would make the tenant a caller-controlled claim again. Keep it bound to ALLOW_DEV_NODE, and keep ALLOW_DEV_NODE out of production. pnpm lint:invocation-log refuses a missing, late or secretless mount.

Dependency-free by design ​

Node built-ins only, no build step, no runtime dependencies — so the initializer can never break at install time.

substrat on npm is not Substrat

It is an unrelated HTML5 build system published in 2013. Substrat's packages are all under the @substrat-run scope. Never npm install substrat.