Skip to content

@norbital-ai/pod

@norbital-ai/pod is the authoring SDK — you define your entire operational system in TypeScript. It owns how workspace code is structured, built, and run: the defineWorkspace() API, the pod CLI, manifest and DDL generation, collection runtime, policy evaluation, approval gates, UI primitives, and the facility ports your host binds at runtime.

You write workspace source (workspace.ts, collections, apps, hooks, automations) and the CLI registers it into the pod-owned application shell. On Core, every commit is built inside an isolated microVM — no Vite config, no build pipeline to run.

What pod owns

  • Authoring SDK — defineWorkspace(), defineConfig(), defineSdk(), collection models, hooks, pipelines
  • Build CLI — norbital build / norbital dev manifest synthesis + Vite build on the pod app shell
  • Build output — manifest.json, incremental DDL, compiled dist/
  • Collection runtime — SQL compilation, policy evaluation, write-then-lock approvals, remotes
  • UI primitives — shared Svelte components tenant apps import from the pod package
  • Facility ports — Db, FileStorage, AIProvider, Secrets interfaces workspace code calls through bindings
Checkpoints and Agent are Core plugins
Checkpoints (versioned releases with sync / go live / rollback) and Agent are Core-only — see Core platform. Pod exposes the ai facility port; Core provides the agent implementation.

What the host owns

Pod defines interfaces; a host provides implementations and injects them as bindings. Core is the reference host. It provides:

  • Credential storage and socket access (Per-tenant Postgres pools, object storage, model APIs)
  • Sandboxed builds per commit in isolated microVMs
  • DDL validation, migration, and bundle serving
  • Auth, billing, and multi-tenant operations

Author → Build → Run

  1. Author — editable workspace source (workspace.ts, modules, apps, seed)
  2. Build — norbital build emits manifest, DDL, and dist/
  3. Run — Core deploys the bundle, provisions the database, and serves it

CLI

Local development and production builds use the same CLI:

norbital dev    # pod SvelteKit app with workspace modules registered
norbital build  # emit manifest + DDL + dist/

On Core, builders trigger builds through Workspace Studio Sync and Go live — the Checkpoints plugin invokes the same CLI inside ephemeral sandboxes. See Workspace Studio.

Facilities and bindings

Workspace code never holds credentials. The host injects one consolidated binding object pod resolves as getRuntimeFacilities():

bindings = {
  db:          HostDbBinding,
  fileStorage: HostFileStorageBinding,
  ai:          HostAiBinding,
  secrets:     HostSecretsBinding
}

Per-request identity (TBaseScope — requestor, org, teams) travels with each invocation separately from facility bindings.

Forbidden in workspace source

  • node_modules/, .svelte-kit/, dist/ committed beside source
  • Declaring svelte, vite, or @sveltejs/* in workspace package.json
  • Local file: dependencies — platform packages resolve from published tarballs at build time

Next steps

Previous Introduction Next Workspace source