Architecture

A practical view of what runs on your machines when you deploy ObjectOS, what data leaves your network, and what doesn't.

The mental model is two thin layers:

1. Metadata — packages of objects / views / actions / flows / agents. Mostly written by the AI Builder against a sandboxed tool API; sometimes hand-edited, always version-controlled and audited.
2. A single Node.js runtime that interprets that metadata into a working application — REST API, Console UI, permissions, jobs, AI tools — all in one process, talking to your database.

No code generation step, no deploy pipeline between "user described what they want" and "it's live". The runtime hot-loads the new metadata after a HITL approval.

What you deploy

One Node.js process per ObjectOS instance. That's it.

┌─────────────────────────────────────────────────────┐
│                  ObjectOS process                   │
│  ┌───────────────────────────────────────────────┐  │
│  │   HTTP dispatcher  (/ · /api · /_console …)    │  │
│  ├───────────────────────────────────────────────┤  │
│  │   Per-project ObjectKernel (LRU cached)       │  │
│  │   ├─ Auth (Better Auth)                       │  │
│  │   ├─ Security (RBAC + row-level + field)      │  │
│  │   ├─ ObjectQL (data engine, generates SQL)    │  │
│  │   ├─ REST API generator                       │  │
│  │   └─ Capabilities loaded per artifact         │  │
│  │      (audit, storage, jobs, queue, AI …)      │  │
│  └───────────────────────────────────────────────┘  │
└──────────┬──────────────────────────────────────────┘
           │
           ▼
   Your business database
   (Postgres / MySQL / SQLite / Turso / MongoDB)

It's a single statically-linked binary's worth of complexity. No sidecar, no Kafka, no separate cache layer required. Add those when you need them; don't pay for them on day one.

Where your data lives

ObjectOS does not call home. No telemetry. No license check. If you cut internet access entirely, it keeps running indefinitely. See Air-gapped.

How a request is served

1. Ingress / TLS termination     (your load balancer)
2. HTTP dispatcher               (security headers, request id)
3. Hostname → project resolution (cached, TTL configurable)
4. Get or build per-project kernel from LRU
5. AuthPlugin    — session cookie, bearer token, or API key
6. SecurityPlugin — RBAC + row-level + field-level checks
7. Route handler — generated REST, declarative action, or custom
8. Data driver   — ObjectQL compiles to SQL / Mongo query
9. Response with X-Request-Id propagated

Steps 4-8 typically execute in < 5ms once the kernel is warm.

The three layers (only matters if you're integrating)

Most customers deploy only ObjectOS. The other two layers exist if you want to know where the artifact comes from:

If you're shipping a single app, you don't need a control plane — compile objectstack.config.ts → dist/objectstack.json in your CI and ship the JSON in the image. If you're running an internal app marketplace with many tenants and apps, the control plane is where the catalog lives.

Boot modes

Mode is auto-detected from environment variables.

Performance characteristics

Why this shape

• One Node process, no sidecars → fits in a docker run, fits in a systemd unit, fits in a Lambda-like environment.
• Per-project kernel, LRU cached → one instance can serve many small apps without paying the warmup cost on every request.
• Generated APIs on top of declared metadata → there's no codegen step in your CI, no client SDK to publish; the API matches your data model by construction.
• All capabilities are optional plugins → image size scales with what you actually use.

Where to go next

• Production Readiness — checklist before exposing it to real traffic.
• Runtime Configuration — wiring databases, caches, and secrets.
• Runtime Capabilities — which optional packages exist and what they enable.