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 hypervisor and no sidecar runtime: Colony starts a fresh worker thread for each artifact inspection or invocation and terminates it when that work settles. The Colony host itself remains always on. 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 — local development and tests use COLONY_POSTGRES_URL with the plain-Postgres provider. Hosted staging and production require Neon and provision a Neon branch per tenant, then apply the migration lineage.
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	Plain Postgres for local development/tests; Neon branches for hosted staging and production, provisioned and migrated by Colony.	You provision, migrate, back up, and monitor your own Postgres.
Builds	bolt sync plus the bolt() 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 loop invocation into a one-shot worker and meters active worker 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 ( Agent 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
            → one-shot workers only during inspection or invocation
        │
        ▼
  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 compiled server bundle: collection, hook, pipeline, automation, function, and envoy runtime
.norbital/migrations/ and schema SQL — incremental tenant migrations
.norbital/dist/ — the compiled client: tenant apps, assets, and the workspace entry

Preview emits additive DDL by default. Destructive schema changes may require an explicit supplement SQL script before Preview completes. Approval applies the exact reviewed migration plan to Live.

What Colony provides

Source store — canonical workspace source in tenant Git repositories and personal worktrees; 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 vite build 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 — plain Postgres in local development/tests; hosted staging and production use one Neon branch per Live tenant plus at most one autosuspending Neon branch for each active Preview
Sync transport — hosts and proxies Bolt’s sync routes so tenant apps reach their replica, stream, and mutations ( Sync engine )
Auth & orgs — Bolt cookie session, email OTP, and team invitations
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 proxy through host.invoke into the bolt runtime 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 .