Colony

Colony is the self-hostable runtime that hosts Bolt workspaces. You bring the workspace source and Colony runs it: it routes tenant paths, compiles the checkout with @norbital-ai/bolt , builds and publishes release artifacts, provisions and migrates the tenant database, binds the facilities (Postgres, files, AI, sync transport, auth), and serves the Workspace Studio. In development the bootstrap converges on every start; production runs the same server.

Bolt defines the workspace; Colony hosts it

Everything before this section describes the authoring SDK, the workspace source contract, and the runtime. This section documents the host that runs it.

Why run Colony?

Every bolt workspace needs a host. Colony is the host the platform itself runs on, so you do not have to assemble the hosting pieces yourself:

One process — no sidecar runtime for invocation: Colony evaluates each tenant invocation in a brand-new isolated-vm context, released the moment the invocation settles, inside an always-on host; artifact inspection alone uses a one-shot worker, and authoring builds run in a disposable KVM-backed microVM. The dev bootstrap converges on every start, so a local environment is always current.
Release artifacts — the development bootstrap compiles configured local checkouts on development starts. Hosted immutable artifacts are built and published only by explicit Preview or release operations; the routed tenant serves exactly the selected artifact.
Tenant databases — COLONY_MODE selects the tenant topology: development always binds the PGlite fleet, production always binds organization-scoped Neon (one branch per Live tenant; at most one autosuspending Preview branch). COLONY_POSTGRES_URL names the control-store Postgres only.
Auth, teams, and billing — cookie sessions, email OTP sign-in, teams and invitations, and Stripe billing are included.
Operations and updates — Colony consumes the @norbital-ai/bolt packages directly, so runtime upgrades land as ordinary package releases. Backup and restore remain explicit operator responsibilities until named-volume backup automation is implemented.

Colony vs. building your own host

The same workspace source runs on both. The difference is who owns each part of hosting it:

Capability	Colony (self-hostable)	Custom host on @norbital-ai/bolt
Deployment & routing	The tenant matrix persists route metadata; release builds and bundle serving are included. Routes do not own workers.	You build, deploy, and serve the workspace, and keep that pipeline working.
Release management	Immutable release artifacts per workspace, built by explicit Preview or release operations and reused without rebuilding.	Your own build, release, and environment management.
Rollback	Restore a prior release artifact; the deployment history keeps the current deployment plus rollback points.	You design, test, and run your own rollback.
Databases	COLONY_MODE selects the tenant topology: development binds the PGlite fleet, production binds organization-scoped Neon (one branch per Live tenant; at most one autosuspending Preview branch), provisioned and migrated by Colony.	You provision, migrate, back up, and monitor your own Postgres.
Builds	bolt sync plus the boltPlugin() Vite plugin on every build and release.	Builds run on your CI, on your infrastructure.
Auth & orgs	Included — cookie sessions, email OTP, teams, and invitations.	You build or integrate your own identity layer.
Billing	Included — one Stripe subscription: a base price plus metered compute and AI usage, with a trial grant at Checkout.	Your own metering, invoicing, and payment collection.
Agent	Included — in-workspace AI assistant under the same ACLs as your apps.	Bolt ships the loop and UI; you bind an ai facility. The same host admits each loop iteration.
Updates & operations	Colony consumes the @norbital-ai/bolt packages directly; backup and restore remain operator-managed.	You track, test, and apply bolt releases yourself.

Choose Colony when you want a working host out of the box; build your own on the bolt packages when you need to own the hosting layer.

Colony surfaces

Workspace Studio is a host plugin — its UI ships inside the compiled Bolt workspace shell, and is surfaced only when a host like Colony provides it. Colony is the host of record for both: @norbital-ai/bolt (Agent is Bolt-owned; Colony admits each run into a fresh isolate and meters active CPU, while facility waits resume inside that invocation):

Workspace Studio — browser UI for editing one personal workbench, building an exact Preview, requesting Review, and managing org settings ( Workspace Studio docs
Agent — Bolt-owned loop, /agent UI, and transcripts; Colony admits each invocation, resumes model and tool waits inside it, and meters active worker CPU ( Norbius docs

Builders ship through Workspace Studio — Preview and approve and release — they do not run their own deploy pipeline.

How a change goes live

  Edit My workbench — source · scripts · skills, no database
        │
        ▼
  Preview — generate/edit DDL → lint · typecheck · health · bundle
            → persistent route metadata + one Neon fork
            → inspection: one-shot worker; invocation: fresh isolate
        │
        ▼
  Request review — every reviewer opens that exact Preview
        │
        ▼
  Approve — apply the reviewed schema plan and fast-forward Live
        │
        ▼
  Rollback (if needed) — restore a prior release artifact from history

Edit — mutable source in My workbench
Preview — one exact workbench commit, persistent route metadata, and an autosuspending database fork; workers are one-shot
Production — deployed release plus the live tenant database

Edit is not apply

Choose Preview to generate editable DDL and validate without changing Live. Only approval fast-forwards the reviewed commit into Live.

Release artifacts

Release artifacts are immutable workspace builds. A successful Preview publishes one frozen bundle to Colony\u2019s artifact store, identified by release and artifact id. Review and release reuse that exact bundle; they never rebuild it. A new commit creates a new artifact, and rollback redeploys a prior artifact rather than rewinding history. See Workspace Studio for the Review tab, toolbar controls, and rollback flow.

A release artifact contains:

server bundle — the guest entry bundle.mjs and its code/*.mjs graph: collection, write contract, pipeline, automation, function, and envoy runtime
.norbital/migrations/ — the host-readable manifest and verified ESM graph, and the authority hosts read
.norbital/dist/ — digest-addressed assets: schema, migration lineage, browser assets, server assets, lockfile, and code

Preview emits additive DDL by default. A destructive change surfaces migration_required: the generated migration is opened for review and edit, and another Publish/Preview is needed. Approval applies the exact reviewed migration plan to Live.

What Colony provides

Source store — canonical live source in tenant Git repositories; each person’s private draft is content-addressed blobs plus a control-store pointer, and the artifact/object store holds immutable build artifacts
Build orchestration — the development bootstrap brings configured local checkouts up at boot. Hosted Preview and release operations invoke the workspace-pinned Bolt toolchain plus bolt sync in a validated temporary materialized tree, publish the immutable artifact, and remove that tree when done
Release registry — the control store tracks each tenant environment\u2019s deployed releaseId and its artifact artifactId ), plus rollback history and workspace source snapshots
Tenant databases — COLONY_MODE selects the tenant topology: development binds the PGlite fleet, production binds organization-scoped Neon (one branch per Live tenant; at most one autosuspending Preview branch)
Sync transport — hosts and proxies Bolt’s sync routes so tenant apps can register live queries, receive SSE apply frames, and push mutations ( Sync engine )
Auth & orgs — Bolt cookie sessions, email OTP, and tenant-native invitation acceptance and success pages. Invitation GETs only inspect; authenticated confirmation consumes the claim, so mail scanners cannot accept it.
Billing — one Stripe subscription: a base price plus metered compute and AI usage, with a trial grant at Checkout
Workspace Studio — browser UI for source edit, preview build, release requests, and the complete tenant topology

What Colony does not own

Colony imports no bolt TypeScript internals. It does not embed tenant logic directly. Collection operations are invoked as signed guest commands into the host.invoke guest dispatch (collections.write, …), where policies and SQL are evaluated. Policy evaluation, approval gates, and SQL compilation always run inside the bolt runtime.

Two-database model

System DB — organizations, routing and release metadata, billing identifiers
Tenant DB — per-org Postgres with collection data, policies, approvals, app records

The control store holds routing and release state. Identity lives in the tenant runtime; collection reads and writes are proxied into the tenant DB through the bolt runtime.

Subscriptions

Base price — one Stripe subscription the tenant is subscribed to through Checkout, with a configured trial for first-time customers
Metered usage — compute and AI usage billed through Stripe billing meters; the deployment names the metered prices

See pricing .