Concepts

Reactor is designed around a small set of ideas that stay constant whether you are on a laptop or in production. This page explains the mental model so the CLI, SDK, and server behavior make sense together.

One project, one manifest

Every Reactor project is defined by reactor.toml at the project root. The CLI walks up the directory tree to find it (stopping at the git root), similar to how package.json or Cargo.toml work.

project_id = "my-app-a1b2c3d4"
name = "My Application"
default_context = "local"

[data]
migrations_dir = "data/migrations"

[[functions]]
name = "hello"
source = "functions/hello"
runtime = "wasm"
entry = "index.ts"

[[sites]]
name = "web"
source = "sites/web"
framework = "static"

[[jobs]]
name = "nightly-rollup"
function = "rollup"
trigger = { type = "cron", schedule = "0 0 * * *" }

Key fields

Field	Purpose
project_id	Stable identifier linking local project to server-side records
name	Human-readable display name
default_context	Which named server connection to use when --context is omitted
[data]	Migration directory and data-related settings
[[functions]]	Declarative function registry — name, source path, runtime
[[sites]]	Site name, source directory, framework (static, nextjs, etc.)
[[jobs]]	Scheduled or event-driven work pointing at a function

Note

Environment variables override server config with the REACTOR_ prefix (e.g. REACTOR_DATABASE__URL). Project manifest values are separate — they describe your app, not the server infrastructure.

What lives outside reactor.toml

Global CLI state — contexts, credentials, default context — is stored in ~/.reactor/config.toml:

default = "production"

[contexts.local]
endpoint = "http://localhost:8080"

[contexts.production]
endpoint = "https://api.reactor.cloud"
org = "acme"

[contexts.production.auth]
kind = "keychain"
service = "reactor"
account = "production"

Keep secrets out of reactor.toml. Use reactor login, keychain storage, or CI environment variables.

Contexts

A context is a named connection to a Reactor server: an endpoint URL, optional org, and auth configuration.

reactor context add staging --endpoint https://staging.example.com --org acme
reactor context use staging
reactor deploy

Contexts let you:

• Switch between local, staging, and production without editing files.
• Share the same project repo across environments.
• Override per-invocation with --context or REACTOR_CONTEXT.

CLI

reactor context list
reactor context show production
reactor deploy --context staging

Environment

export REACTOR_CONTEXT=production
export REACTOR_TOKEN=rk_svc_...
reactor deploy

Token resolution order: --token flag → REACTOR_TOKEN env → context-specific env → OS keychain.

Capabilities

Reactor exposes eight user-facing capabilities. Each one follows the same pattern:

1. HTTP API — versioned routes (/auth/v1, /data/v1, /fn/v1, …)
2. SDK module — @reactor/auth, @reactor/data, etc., composed in @reactor/client
3. CLI verbs — reactor functions …, reactor data …, reactor jobs …
4. Rust trait + adapters — swappable backends per deployment grade

┌─────────────────────────────────────────────────────────┐
│                     Your application                     │
│              (SDK, curl, or CLI scripts)                 │
└─────────────────────────┬───────────────────────────────┘
                          │ HTTP
┌─────────────────────────▼───────────────────────────────┐
│                   reactor-server                         │
│  ┌─────────┐ ┌──────┐ ┌─────────┐ ┌───────────┐        │
│  │ Identity│ │ Data │ │Functions│ │   Sites   │  ...   │
│  └────┬────┘ └──┬───┘ └────┬────┘ └─────┬─────┘        │
│       │         │          │            │               │
│       └─────────┴──────────┴────────────┘               │
│                     Shared Postgres                      │
└─────────────────────────────────────────────────────────┘

Capability reference

Capability	API prefix	SDK accessor	CLI prefix
Identity	/auth/v1	reactor.auth	reactor login, org commands
Data	/data/v1	reactor.from(), reactor.rpc()	reactor data
Storage	/storage/v1	reactor.storage	(SDK-first today)
Functions	/fn/v1	reactor.functions	reactor functions
Jobs	/jobs/v1	reactor.jobs	reactor jobs
Sites	/sites/v1	reactor.sites	reactor sites
Gateway	/gateway/v1	@reactor/ai	(config-driven)
Connect	/connect/v1	@reactor/connect	(config-driven)

Capabilities can be enabled or disabled at the server level via cargo features and server config. Your project manifest declares what your app uses; the server decides what is available.

Deployment topologies

Deployment topologies describe where and how Reactor runs, expressed as <Edition><Size>@<platform>. The invariant:

The same SDK call, CLI command, and project file work on every topology. Adapters differ; semantics are uniform up to documented contract differences.

Token	Name	Target	Identity	Data store	Functions runtime
O1	Local	Desktop / dev binary	Embedded	SQLite + RLS simulation	In-process WASM
O2	Single node	One VPS, Docker Compose	Embedded or external	PostgreSQL	Docker subprocess / WASM
O4	Managed cloud	Fly, Render, Railway	Reactor Identity	Managed Postgres	Fly Machines / Workers
E6	Enterprise	Customer AWS / GCP	Reactor on EKS/ECS	RDS / Aurora	Lambda / Fargate
C6	Reactor.cloud	Hosted by AtomicoLabs	Reactor Identity	Per-region Postgres	Firecracker microVMs

Choosing a deployment

If you need…	Start with
Fastest local iteration	O1 / reactor dev
Cheap single-server production	O2 on a VPS
Minimal ops, managed infra	O4 or C6
Compliance, existing cloud contract	E6

Caution

Smaller sizes may weaken guarantees for realtime delivery, job concurrency, or cold-start latency. Documented in Deployment topologies.

The adapter mental model

Under the hood, each capability is a Rust trait with multiple adapters — one per deployment topology.

Capability trait (stable API contract)
        │
        ├── size 1 adapter  (SQLite, local FS, in-process)
        ├── size 2 adapter  (Postgres, local/MinIO, Docker)
        ├── size 4 adapter  (Neon, R2, Fly Machines)
        └── C6 adapter      (Reactor.cloud managed)

As an application developer you rarely touch adapters directly. You:

1. Write SQL migrations and RLS policies (Data).
2. Export HTTP handlers from function files (Functions).
3. Declare resources in reactor.toml.
4. Call the SDK or CLI.

Reactor operators choose adapters when configuring reactor-server or selecting a hosted plan.

Example: Functions across topologies

Topology	What happens when you call reactor.functions.invoke('hello')
O1	In-process WASM handler, localhost only
O2	WASM or container subprocess on the same host
C6	Request routed to an isolated microVM, cold start possible

The invoke API and response shape stay the same.

Multi-tenancy and security

Organizations

Reactor supports multi-tenant SaaS through organizations:

• Users belong to one or more orgs with roles.
• Data rows are scoped by org via RLS.
• Contexts can include --org to set the active org.

Row-level security

Every authenticated Data request sets Postgres session variables:

Variable	Meaning
reactor.user_id	Authenticated user’s UUID
reactor.org_id	Active organization
reactor.role	User’s role in that org

RLS policies reference these variables. Service-role keys bypass RLS for admin tasks.

API key tiers

Key type	Use case	RLS
rk_pub_…	Browser / mobile clients	Enforced
rk_svc_…	Server-side, CI, admin	Bypassed

Tip

Use publishable keys in frontend code. Keep service keys in environment variables and CI secrets only.

Bundles and deploy artifacts

reactor build produces a bundle — a compressed archive of everything needed to run your app on a target server:

• SQL migrations
• Compiled function artifacts
• Site static assets or framework build output
• Manifest snapshot

.reactorignore excludes files (like node_modules/ and .env) from bundles, similar to .dockerignore.

reactor deploy uploads the bundle, applies migrations, and rolls out functions and sites atomically per project.

How the pieces fit together

reactor.toml          ~/.reactor/config.toml
     │                         │
     │    project resources    │   server connections
     ▼                         ▼
reactor build  ──►  bundle  ──►  reactor deploy  ──►  reactor-server
                                                          │
                     @reactor/client ◄──── HTTP ──────────┘

1. Develop locally with reactor dev (sizes 1–2 embedded).
2. Declare functions, sites, and jobs in reactor.toml.
3. Connect to remote servers via contexts.
4. Deploy with reactor build && reactor deploy.
5. Call the same SDK against any grade.

Related reading

• Introduction — platform overview and who Reactor is for.
• Quickstart — install CLI and run your first server.
• Adapters — operator-focused adapter reference.
• Configuration — server-side config and env overrides.