Quickstart

This guide gets you from zero to a running Reactor server on your machine. By the end you will have a project directory, a local dev server with ephemeral Postgres, and a deployed bundle ready for a remote target.

Prerequisites

• macOS or Linux — Windows is supported via WSL2.
• curl — for the install script (optional).
• Homebrew (macOS/Linux) or Rust 1.78+ — for CLI installation.

Note

You do not need to install PostgreSQL manually for local development. reactor dev spins up an embedded database automatically. For self-hosted production servers, see Self-hosting.

Install the CLI

Homebrew (recommended)

brew install reactor-cloud/tap/reactor

Verify the installation:

reactor version

Install script

curl -fsSL https://reactor.cloud/install.sh | sh

Add the install directory to your PATH if prompted, then verify:

reactor version

Cargo

Requires Rust 1.78 or later:

cargo install reactor-cli

Or build from source in the monorepo:

git clone https://github.com/reactor-cloud/reactor-cloud.git
cd reactor-cloud
cargo build --release --package reactor-cli

Expected output (version numbers will vary):

reactor-cli 0.1.0
reactor-server (not running)

Create a project

Initialize a new project in the current directory’s parent:

reactor init my-app
cd my-app

This creates:

Path	Purpose
reactor.toml	Project manifest — ID, name, capability paths
.reactorignore	Patterns excluded from deploy bundles
functions/hello/index.ts	Sample HTTP function
data/migrations/001_sample.sql	Sample database migration
functions/, sites/, data/migrations/	Empty scaffold directories

Inspect the manifest:

reactor project show

Tip

Project IDs are generated automatically (my-app-a1b2c3d4). You rarely need to change them — they tie your local project to a server-side project record on deploy.

Start local development

From your project root:

reactor dev

reactor dev does the following:

1. Starts an embedded PostgreSQL instance (ephemeral — data resets when you stop).
2. Runs pending SQL migrations from data/migrations/.
3. Launches reactor-server with all capabilities enabled.
4. Prints the local endpoint (default http://localhost:8080).

Leave this terminal open. Open a second terminal for the commands below.

Background mode

Prefer a daemon-style server?

reactor up      # start in background
reactor status  # check health
reactor down    # stop

Verify the server

CLI

reactor doctor
reactor data migrate   # ensure migrations are applied
reactor functions list

curl

# Health check
curl http://localhost:8080/health

# Invoke the sample function
curl -X POST http://localhost:8080/fn/v1/hello \
  -H "Content-Type: application/json" \
  -d '{"name": "Reactor"}'

Expected response:

{"message": "Hello, Reactor!"}

JavaScript

npm install @reactor/client

import { createClient } from '@reactor/client';

const reactor = createClient('http://localhost:8080');

const { data, error } = await reactor.functions.invoke('hello', {
  body: { name: 'Reactor' },
});

console.log(data); // { message: "Hello, Reactor!" }

Run database migrations

Migrations run automatically during reactor dev, but you can apply them manually:

reactor data migrate

Inspect a table after migration:

reactor data inspect items

Authenticate (optional for local dev)

Local dev often runs with relaxed auth. When you connect to a remote server, log in first:

reactor login
reactor whoami

Tokens are stored in your OS keychain or an environment variable, depending on context configuration.

Configure a deploy target

Before deploying, add a context — a named connection to a Reactor server:

# Local (created automatically by reactor dev in many setups)
reactor context add local --endpoint http://localhost:8080

# Reactor.cloud production
reactor context add production \
  --endpoint https://api.reactor.cloud \
  --org my-org

reactor context use production
reactor login

List and inspect contexts:

reactor context list
reactor context show production

Caution

Never commit API tokens or service keys to git. Use reactor login, environment variables, or your CI secret store.

Build and deploy

When you are ready to push to a remote server:

# Build a deployment bundle (validates manifest, packages functions/sites/migrations)
reactor build

# Deploy to the active context
reactor deploy

Deploy runs migrations on the target, uploads function bundles, and publishes site assets. Progress is printed to the terminal; use --output json in CI.

Human output

✓ Validated reactor.toml
✓ Built bundle (1.2 MB)
✓ Applied 1 migration
✓ Deployed 1 function
✓ Published site "web"
Deployed to production (https://my-app.reactor.cloud)

JSON output

reactor deploy --output json

{
  "ok": true,
  "data": {
    "context": "production",
    "endpoint": "https://api.reactor.cloud",
    "functions_deployed": 1,
    "sites_deployed": 1,
    "migrations_applied": 1
  }
}

Common issues

Symptom	Fix
project manifest not found	Run commands from the project root or pass --manifest path/to/reactor.toml
connection refused on deploy	Check reactor context show — is the endpoint correct? Is the server running?
Port already in use	Stop other services on :8080 or set REACTOR_DEV_PORT=9090
Migration failed	Run reactor data inspect <table> and fix SQL in data/migrations/

Run diagnostics anytime:

reactor doctor

What’s next?

• Your first app — end-to-end tutorial with auth, data, a function, and site deploy.
• Concepts — deep dive into reactor.toml, contexts, and deployment grades.
• CLI reference — full command list and global flags.