Scale Mode

Scale mode transforms Synapse from a single-process application into a distributed job execution system. Your main Synapse instance continues to manage the UI and definitions. Separately deployed workers pull jobs from a Redis queue and execute them in parallel — across as many machines as you need.

---

Standalone vs scale mode

	Standalone	Scale Mode
API response	Blocks until the run completes	Returns 202 Accepted immediately with a run_id
Execution model	In-process, synchronous	ARQ workers pull jobs from Redis queue
Concurrency	Limited by request thread pool	Unlimited — add workers horizontally
State storage	Local JSON files on disk	Postgres — shared across all instances
Events	Returned in response body	Redis Streams → SSE (reconnectable, replayable)
Fault tolerance	In-process crash loses the run	Worker crash → job requeued automatically
Multi-instance	Not supported	Fully supported — API servers are stateless

Switch between modes at any time from Settings → Scale without redeploying. When scale mode is disabled, the main instance falls back to inline execution and all V2 API responses become synchronous again. In-flight jobs on workers continue until they complete — toggling the mode does not cancel running jobs.

---

When to enable scale mode

• High job volume — you need more than 5–10 concurrent orchestration runs simultaneously
• Long-running jobs — orchestrations take minutes or hours and you cannot hold HTTP connections open for the full duration
• High availability — a single-process crash should not lose in-flight work; workers requeue jobs automatically on restart
• Multi-tenancy — you need per-tenant queue limits, isolation, and rate limiting across multiple customers or teams
• Horizontal scaling — you want to add compute capacity by spinning up worker containers rather than upsizing a single machine
• Observability requirements — you need distributed tracing, Prometheus metrics, per-run cost and token tracking, and a run history dashboard

---

What you need

Component	Required	Notes
Redis 6+	Yes	Job queue, SSE event streams, cancellation signals, worker heartbeats
Postgres 14+	Yes	Shared definitions, run state, worker registry, analytics, dead-letter queue
S3 or compatible	No	Shared vault files and execution logs across workers. Required when running multiple workers that handle sequential jobs in the same session.

Redis is the only hard dependency to start. You can enable scale mode with just a Redis URL and run one worker. Postgres becomes required as soon as you deploy a worker — workers read all orchestration and agent definitions from Postgres, not from local JSON files on the main instance. S3 is optional for single-worker deployments.

---

Quick start

1. Connect Redis

Go to Settings → Scale → Redis Connection. Enter your Redis URL and click Test.

redis://your-redis-host:6379/0

2. Enable Scale Mode

Flip the Enable Scale Mode toggle and click Save Scale Config. The V2 API now routes all jobs through the Redis queue.

3. Connect Postgres

Expand the Postgres Sync section. Enter your Postgres URL and click Test.

postgresql://user:password@your-pg-host:5432/synapse

4. Sync definitions

Click Sync Now. This pushes all your orchestrations, agents, tools, and MCP server configurations from local JSON files to Postgres, so workers can read them.

5. Start a worker

Pull the worker image and start it with your Redis and Postgres URLs:

docker run -d \
  --name synapse-worker-1 \
  -e REDIS_URL="redis://your-redis-host:6379/0" \
  -e SCALE_POSTGRES_URL="postgresql://user:password@your-pg-host:5432/synapse" \
  -e WORKER_CONCURRENCY=10 \
  -p 9000:9000 \
  --restart unless-stopped \
  synapseorchai/synapse-ai-worker:latest

The worker registers itself in Postgres on startup and appears in the Workers panel in Settings → Scale within 30 seconds.

tip

Verify the worker is healthy before sending jobs:

curl http://localhost:9000/health

{"status": "ok", "worker_id": "worker-abc123", "active_jobs": 0, "uptime": 12.4}

---

Next steps

• Architecture — how the components interact, Redis key patterns, Postgres schema, worker lifecycle
• Configuration — every setting in the Scale UI explained, full environment variable reference
• Deployment — Docker Run, Docker Compose, Kubernetes with KEDA, production checklist