creator-os-runtime — Architecture (behavioral spec)

One process. One command. One source of truth. Max capability inside the box, min authority outside.

What it is

The runtime is the credential proxy + policy gate + ledger that sits between agents (the COG, sub-agents, Claude sessions, MeshMarket agents) and real infrastructure (Railway, Cloudflare, GitHub, Stripe). Nothing outside the runtime ever holds a root credential. Agents hold grants — signed, scoped, budgeted, expiring capability tokens — and every real-world action is a controlled exit the runtime performs on their behalf after verifying the grant.

For "Creator-OS for everyone" this is the same box, multi-tenant: each creator is a tenant, their subscription tier is literally a grant budget, and the COG is the agent that turns "launch my tip bot" into grants + worker deploys without the creator seeing any of the plumbing.

Actors

Invariants (the fail-safe contract)

The COG loop

intent ("launch a tip-alert worker for tenant X")
  → COG.plan   : deterministic template planner (+ optional LLM refinement, re-validated)
  → proposal   : { grants: [...attenuated child specs], deploys: [...deploy intents], estimate }
  → gatehouse  : ceilings + hard rules + tier → sign each grant or deny the whole proposal
  → exit       : for each deploy intent → dry-run plan → (if confirmed & armed) Railway GraphQL
  → ledger     : reserve → settle/release, every step referenced by ids
  → events     : bus entries (cog.planned, grant.issued, deploy.requested, deploy.status, …)

requireDryRun (default on for a worker name's first deploy) returns the plan with executed:false; a second call with confirm:true executes. Without RAILWAY_API_TOKEN (or a tenant OAuth token) the exit is unarmed and always returns the plan — the loop is safe to run before any secret exists.

Brain + memory (every app ships with both)

Memory is the REMEMBER chamber, per tenant: records keyed by (partition, key) with content, tags, a monotonic version, and tombstones — the same LWW model as cognitive-mcp / the bridge. Partitions: tenant (shared), agent:<sub>, worker:<name>, fan:<id>. Search is Postgres full-text + substring. Surfaces: POST/GET/DELETE /api/memory (caps memory.read / memory.write, partition scope enforced) and MCP tools memory_search, memory_write, memory_forget.

The COG remembers. cog.plan pulls prior evidence (memory matching the intent + template) and prior failures on that template before proposing; the proposal carries evidence[] and warnings[]. cog.execute writes back what happened (agent:cog / deploy:<name>). A Railway Deployment.failed webhook writes worker:<name> memory — so the next plan for that worker already knows.

Brain is the event bus. Inbound: /webhooks/brain (signed). Outbound: every events row is fanned out to BRAIN_URL (signed with BRAIN_WEBHOOK_SECRET, header X-Brain-Signature) through the outbox table — retries with backoff, gives up after 10 attempts with the error kept, POST /api/admin/outbox/drain for a manual/scheduled push, /api/admin/outbox to look.

Sync peer. The runtime speaks the bridge's seam protocol both ways: it serves GET /sync/changes?since=<version> and POST /sync/apply (bearer COG_SYNC_TOKEN; records carry partition = "<tenant>/<partition>", LWW on version, tombstones honored), pushes each memory change to COG_BRIDGE_URL/sync/apply through the outbox, and pulls with POST /api/admin/memory/pull (cursor kept in settings). Point the cognitive-mcp bridge at the runtime and the runtime at the bridge: memory flows both directions, and the box keeps working when either side is away.

Subscription SaaS = grant budgets

Prices are set in Stripe; the runtime maps price_id → tier via STRIPE_PRICE_MAP (JSON). Stripe webhooks drive tenant state: checkout.session.completed activates, customer.subscription.updated re-tiers, customer.subscription.deleted / invoice.payment_failed suspend. A suspended tenant's grants fail verification (fail closed) until resumed.

Surfaces

Integrations and arming

Every integration is optional and reported by /health.armed. Missing secret ⇒ the dependent route returns 503 {armed:false, needs:"NAME"}.

Storage

Postgres via Bun.sql. Tables: settings, tenants, grants, ledger, deploys, webhook_events, events, vault, oauth_states, breakglass, docs, memories, outbox. Schema is created idempotently at boot (CREATE TABLE IF NOT EXISTS). Counters (reserved_*, settled_*) live on the grant row and are updated inside transactions; the ledger table is the audit trail.

Over-the-top layer (designed, not yet shipped)