Deployment Topologies

Reactor ships as a single Rust workspace with one unified HTTP surface. How you run it is described by three independent axes:

• Edition — who operates it and under what license (O / C / E)
• Size — how decomposed the topology is (1–6, 10+)
• Platform — where it runs (@fly, @aws, …)

Combine them into a single token: <Edition><Size>@<platform> — for example O2, C6@fly, E5@aws.

One HTTP contract, every topology

The SDK, CLI, and admin API behave identically across editions and sizes. Your application code never branches on topology — only your infrastructure does.

Edition

Code	Edition	Who operates it
O	Open Source	You — self-hosted, no license
C	Commercial Cloud	We operate it (managed Reactor.cloud)
E	Enterprise	The customer operates it, under license

Size

Size describes topology decomposition, not raw capacity. Each rung externalizes one more component.

Size	Name	Layout
1	Local	One process, embedded Postgres + vault, 127.0.0.1 only
2	Single node	One box: all capabilities + Postgres + OpenBao co-located, TLS via reverse proxy
3	External DB	App node(s) + managed/external Postgres; vault still embedded
4	Shared infra	External DB + one infra node (NATS + OpenBao + gateway co-located)
5	Dedicated gateway	External DB + standalone gateway/edge tier; NATS + OpenBao still combined
6	Decomposed	Every component independent: NATS, OpenBao, gateway, pooler, app pool
10+	Elastic	Autoscaling pools, multi-region, HA — use +ha, +mr, +as modifiers

Platform

Tag	Target
@local	Laptop / developer machine
@fly	Fly.io
@aws	Amazon Web Services
@azure	Microsoft Azure
@gcp	Google Cloud
@onprem	Customer datacenter / bare metal

Modifiers append to the size: +ha (DB/secret HA), +mr (multi-region), +as (autoscale). Example: C5+ha@fly.

flowchart LR
  S1[1 Local] --> S2[2 Single node]
  S2 --> S3[3 External DB]
  S3 --> S4[4 Shared infra]
  S4 --> S5[5 Dedicated gateway]
  S5 --> S6[6 Decomposed]

Size 1 — Local

Reactor Studio embeds reactor-server as a library inside a Tauri desktop shell. One process, one Postgres (local or Docker), bind address 127.0.0.1 only. Typically O1@local.

Characteristics:

• All capabilities composed in-process via InProcessAuthClient — no inter-service HTTP
• Cargo feature g1-tauri trims heavy adapters (AWS Lambda, Bun warm pool)
• Binary size budget: ≤ 30 MB stripped
• TLS termination handled by the desktop shell or not at all (localhost only)

When to use

• Day-to-day development with Reactor Studio
• Prototyping without cloud spend
• Demos and offline environments
• AI agent workflows that need local filesystem + shell access

When to skip

• Production traffic (use size 2+)
• Team-wide shared environments
• Anything requiring public HTTPS endpoints

# Reactor.toml — size 1 (local) minimal
[project]
name = "my-app"
id = "proj_dev_local"

[server]
bind = "127.0.0.1:8000"

[database]
url = "postgres://reactor:reactor@127.0.0.1:5432/reactor"

[admin]
token = "dev-admin-token"
allow_remote = false

[auth]
data_key = "base64-encoded-32-byte-key"
public_url = "http://127.0.0.1:8000"

Studio integration

Opening a folder in Reactor Studio scaffolds .reactor/ and can start an embedded server automatically. See Reactor Studio for the full workflow.

Size 2 — Single node

The production sweet spot for self-hosters. One reactor-server binary runs every enabled capability against one Postgres and one filesystem, with OpenBao (or embedded vault) on the same box. Put Caddy or nginx in front for TLS. Typically O2 or E2.

Characteristics:

• Full capability bundle via g2-full Cargo features (auth, data, storage, functions, jobs, sites)
• Boot target: listening in under 1 second
• Admin surface at /_admin/* for deploy, doctor, logs
• Background tasks (job scheduler, signed-URL janitor, Bun warm pool) managed by the unified binary

When to use

• Self-hosted production for a single project
• Fly.io, Hetzner, DigitalOcean single-machine deploys
• Teams that want full control without Kubernetes

Sizing

Workload	CPU	RAM	Storage
Dev/staging	1 vCPU	1 GB	10 GB
Small prod	2 vCPU	4 GB	50 GB
Active prod	4 vCPU	8 GB	100 GB+

# Typical size 2 stack
docker compose up -d          # postgres + reactor-server
caddy reverse-proxy :443      # TLS termination
reactor deploy                # push bundle via /_admin/deploy

See Self-hosting for Docker, Compose, and Fly.io walkthroughs.

Sizes 3–6 — Decomposed

When you need independent scaling, blast-radius isolation, or managed multi-tenancy, externalize components one rung at a time. Each capability can run as its own binary (reactor-auth-server, reactor-data-server, …) mounting the same router as the unified binary — the HTTP contract is byte-identical.

Characteristics:

• Scale functions workers separately from the data API
• Run wasmtime in its own address space (functions isolation)
• Swap storage backend to S3 without touching auth
• Microservices auth mode: capabilities call reactor-auth-server over HTTP

Size 3 — External DB

App server(s) + managed/external Postgres (Neon, RDS, Supabase). Vault stays embedded or env-injected. First externalization step.

Size 4 — Shared infra

External DB + one infra node co-locating NATS, OpenBao, and the gateway. Cheapest decomposed option.

Size 5 — Dedicated gateway

Gateway/edge broken out as its own tier; NATS + OpenBao still combined. App pool scales behind the gateway. (Today’s *5@fly reference topology.)

Size 6 — Decomposed

Every component independent — separate NATS, OpenBao, gateway, connection pooler, and app pool. Control plane routes per project. This is what reactor cloud create provisions. (Today’s *6@fly reference topology.)

Escape hatch: remote capability

At size 2 you can run reactor-functions-server separately while keeping other capabilities merged. Set [functions] mode = "remote" with a URL in Reactor.toml. The reverse-proxy stub for this is planned for v0.2 — today, run fully split (size 5–6) or fully merged (size 2).

C6@fly — Commercial shared cluster

The managed tier. Stateless reactor-shared instances front a shared PostgreSQL cluster (one database per project: tenant_<ref>), NATS JetStream for realtime, Supavisor for connection pooling, and OpenBao for secrets — a size 6 decomposed topology that we operate (edition C).

Characteristics:

• Host-based routing: {project_ref}.reactor.cloud
• Per-tier quotas (requests/min, storage, bandwidth)
• Control plane handles provisioning, deploy queue, domain verification
• No infrastructure to operate — reactor cloud create and reactor deploy --context cloud

Resource	Free tier limit
Requests/minute	1,000
Concurrent functions	10
Database connections	5
Storage	1 GB
Bandwidth/month	5 GB

# C6@fly workflow
reactor cloud login
reactor cloud create my-saas --region iad
reactor deploy --context cloud --project my-saas
reactor cloud logs my-saas --follow

Control plane is optional

reactor-server stays clean. The control plane is a separate service — self-hosters at sizes 1–6 (editions O/E) never need it.

Choosing a deployment

Question	O1	O2	O5/E5	C6@fly
Local dev only?	✓
Single project, own infra?		✓	✓
Need per-capability scaling?			✓
Multi-tenant SaaS on Reactor?				✓
Zero ops burden?				✓
Offline / air-gapped?	✓	✓

Typical path: Start at O1 with Studio → deploy to O2 or C6@fly for production → graduate to size 5–6 when traffic or compliance demands isolation.

Migrating between sizes

Moving between sizes does not require application rewrites:

1. Export your Postgres database (pg_dump)
2. Copy blob/function/site directories from .reactor/ or /data
3. Point Reactor.toml at the new topology’s infrastructure
4. Run reactor-server migrate (or POST /_admin/migrate)
5. Deploy your bundle via CLI or /_admin/deploy

Immutable project ID

Keep [project].id stable across migrations. Subdomain refs and JWT issuer claims derive from it.

Related

• Self-hosting — O2 Docker, Compose, Fly.io
• Configuration — full Reactor.toml reference
• Architecture overview — Rust workspace and capability model