Skip to content

Bolt framework

Bolt framework

Bolt is the framework a workspace is written in: an authoring surface of declaration functions, a compiler that turns a workspace into one portable artifact, and an engine any host runs. It knows nothing of any particular host — Colony is one host, and bolt start on your own server is another.

The packages

  • @norbital-ai/bolt — seventeen declaration functions (workspace, secrets, team, app, group, kiosk, messages, model, relationship, customField, collection, integration, pipeline, policy, envoy, mcp and automation) and the types their signatures use. Its /client entry is $bolt, /test is the test kit, and /engine is the engine a host embeds.
  • @norbital-ai/bolt-server — bolt start, the self-host server, which implements every host port.
  • @norbital-ai/ui — the views, inputs and layout pages are built from.
  • @norbital-ai/std — value libraries: decimals, dates, calendars, zones, sheets, formulas, PDF documents and more.
  • @norbital-ai/doctor — the static rules bolt check runs.

Principles

  • Declared first. Anything a declaration can say is declared, so the host enforces it on every path, renders it for agents, and routes live queries by it. TypeScript is the escape hatch, and every place it may appear is typed and bounded.
  • Declarations are data. Field kinds, inputs, predicates, triggers, approval flows and limits are typed object literals, and code bodies attach in their own statements. Only the declaration functions are values.
  • Everything addresses collections. A model is storage; its collection is the exposed portion every surface names.
  • One write path. Pages, agents, automations, API keys, imports, integration feeds, approval decisions and inbound messages all call act on a collection and pass through its transform.
  • Two kinds of tenant code. Transactional code — transforms, queries and actions — has no external I/O, and neither do an integration’s pure bodies (a feed’s map, an outbound rule’s build). Automations and an integration’s durable bodies (a feed’s read, an outbound rule’s run) do their I/O through typed facilities, and each effect is journalled.
  • Nothing silent. No default read caps, no default retries, no deletes by omission, no silent truncation. Every budget has a typed error.
  • Optional providers are never required. AI, geocoding, PDF rendering and mail transports are facilities a host may have; without one, the call answers Unavailable, and the build never demands it.

Topology

Browser                         Host (bolt-server, Colony, or the test kit)
───────                         ──────────────────────────────────────────────
$bolt, ui views   ── /q ──────►  session → actor → authority
  optimistic      ── /act ────►  query compiler: Where → SQL, masks, cursors
  paint, settled  ── /live ───►  write pipeline: allowlist → grant → transform
  by the outcome     (SSE)         → approval route → one statement
                  ── /files ──►  live engine: routes each commit to its views
                  ── /session ►  runs and queue → deadlines port
                                 agent loop, envoys, MCP client, integrations
                                 host ports: database, files, secrets, AI, …
                                        │                        │
                                        ▼                        ▼
                                 Postgres 18 per tenant    guest isolates:
                                 (bolt-server PGlite; Colony local Postgres / hosted Neon) tenant code only,
                                                           2 s CPU, 256 MiB

The engine runs host-side: plain reads and writes, policy evaluation, imports, seeds and live deltas spend no guest CPU. Tenant code — transforms, queries, actions, automation runs and integration bodies (a feed’s read or map, an outbound rule’s build or run) — runs in a fresh isolate per invocation, with at most 2 s of guest CPU and 256 MiB, and each I/O response has a 20 s idle limit. Streaming progress resets that deadline. Bolt and Colony use PGlite locally and in tests; hosted Colony uses a PostgreSQL control store and one Neon project per tenant.

One artifact

bolt build emits one artifact: the manifest (pure data), the schema, the guest bundle of tenant code, the client bundle, assets and skills, with seed packs beside it. The artifact carries a contract digest, and a host implements a set of contract digests, so retained releases stay activatable across a host upgrade.

Host ports

The engine takes one configuration of ports: database, files, deadlines, secrets, AI, speech, document conversion, geocoding, web reads, push, integration links, metering, tenancy and membership. bolt-server implements every one for self-hosting, and Colony implements them for the managed cloud. Nothing in a Bolt package names a host.

Internals

The architecture guides go one level down: