Configuration

REDIS_URL and SCALE_POSTGRES_URL in the environment override the values saved in Settings → Scale, which is usually how a container deployment configures this. Several other settings are read only from the environment — each section below says which. The screen shows each of them read-only, with the value in effect on the main instance and the variable that sets it: change the variable and restart.

---

Redis connection

Redis URL

The connection string for your Redis instance. Test checks it without saving.

The database index at the end (/0) is optional and defaults to 0. Use a dedicated database index if you share a Redis instance across applications.

A redis+cluster:// URL is detected automatically. The job queue itself is served from the first node in the list; the cluster client is used for event streams.

Queued jobs are keys in Redis. Don't run it with an eviction policy that can remove them, and turn on persistence (AOF) so a Redis restart keeps the queue — see Deployment → Production checklist.

Enable scale mode

This switch does not start or stop scale mode, which depends only on the Redis URL at startup. Its one effect today is to turn off local (stdio) MCP servers, which scale mode never runs anyway.

Worker concurrency

The number of jobs a worker process runs at once. Read only from the WORKER_CONCURRENCY environment variable, which each worker takes from its own environment — set the variable on each worker. The screen shows the main instance's value, read-only.

Workers use asyncio, so concurrent jobs run as coroutines, not threads:

• For I/O-heavy workloads (LLM API calls, web requests, database queries), 10–20 per worker is a reasonable starting point. The worker spends most of its time waiting on external services, so concurrency translates directly to throughput.
• For CPU-heavy workloads (local model inference, large data processing), keep concurrency lower (3–5) and run more worker instances in parallel.

Different worker pools can run with different WORKER_CONCURRENCY values.

---

Postgres

The main instance and the workers use one Postgres database, which is SynapseOrch's store. There is nothing to sync: a workflow, agent, tool or MCP server saved in the UI is in the database the next job reads, and each job reads its tenant's settings — model keys included — at the start.

Postgres URL

Test checks the connection without saving.

Left empty, the scale layer uses SYNAPSE_DB_URL. SynapseOrch converts postgresql:// and postgres:// to the postgresql+asyncpg:// driver form for you, here, in SCALE_POSTGRES_URL and in SYNAPSE_DB_URL.

PgBouncer mode

Opens and closes a connection per query instead of keeping a pool, which PgBouncer in transaction pooling mode requires. SynapseOrch does not run PgBouncer; this is for one you put in front of Postgres yourself. It is read only from the PGBOUNCER_MODE=1 environment variable; Settings → Scale shows the main instance's value, read-only. Set the variable on the main instance and on every worker when their Postgres URL points at PgBouncer, and not otherwise — it adds a connection per query.

---

S3 storage

When a bucket is configured, it replaces SYNAPSE_BLOB_DIR as the blob store: the vault, run logs, notifications and cached responses are written to the bucket, in the main instance, in every worker, and in the tool processes they start. Keys are <prefix>/<tenant>/… — synapse/default/vault/notes.md on a single-tenant install with the default prefix. With one bucket shared by every process, a deployment across several hosts needs no shared directory. See Scale Mode → What you need.

The bucket is read when a process starts, from S3_BUCKET or else the saved setting, so a change takes a restart. Set the S3_* variables on every process — in .env for Docker Compose — so each one uses the same bucket. Nothing already in SYNAPSE_BLOB_DIR is copied to the bucket.

S3 bucket

The name of the bucket. It must already exist, and the credentials need s3:GetObject, s3:PutObject, s3:DeleteObject and s3:ListBucket. Test checks access.

Region

The AWS region where the bucket is located.

Key prefix

All objects are stored under this prefix. Useful when sharing a bucket across deployments.

Access key ID and secret access key

IAM credentials for S3 access. Leave both blank to use the environment's AWS credentials instead — an instance profile, an ECS task role, EKS IRSA, or any other credential chain mechanism.

Endpoint URL

Leave blank for AWS S3. Set this to use an S3-compatible object store:

---

Workers

Workers lists the workers registered in the workers table — id, status, active and maximum jobs, and health address — when the main instance is itself in scale mode. It does not refresh on its own; use the refresh button. Each worker can be health-checked, which calls its /health address, or removed from the list.

A worker registers itself when it starts and on each heartbeat; there is nothing to add by hand.

The Scale screen also shows analytics for recent runs, a lookup by run or session id, the Live queue, and Failed jobs (DLQ) with a retry for each. A retry, like Resume from failure on a run a worker ran, is queued for the workers rather than run inside the API process.

---

Observability

OTLP endpoint — or the OTLP_ENDPOINT variable — turns on OpenTelemetry export to your own collector, from the API and every worker: ids, timings, token counts and cost, never prompts, answers or tool data. It applies on restart and needs the telemetry packages, which the Docker images carry.

Metrics token is read only from METRICS_TOKEN. With it set, the API serves Prometheus metrics at GET /api/v2/metrics, with the token as a Bearer token. The screen shows whether one is set, never the token.

See Telemetry for what is exported and how to try it locally.

Max global queue depth

When the queue holds this many jobs, new V2 run submissions return 503 Service Unavailable with Retry-After: 60. A backpressure valve against traffic spikes. Read only from MAX_GLOBAL_QUEUE_DEPTH.

Rate limit per tenant

Maximum V2 run submissions per second, per tenant. Above it, requests return 429 Too Many Requests. Read only from RATE_LIMIT_PER_TENANT_RPS.

A tenant also can't have more than 1,000 queued, running or paused runs at once; the next submission returns 429.

---

Environment variables reference

Pass these to the worker image with -e, --env-file, a Kubernetes Secret or ConfigMap, or a Compose environment: block. The connection, database and storage variables apply to the main instance and API replicas too.

Required

Optional

Worker tuning

Database

Storage

Events and limits

OTLP_ENDPOINT and METRICS_TOKEN are described under Observability. RUNS_RETENTION_DAYS and K8S_MODE are read but currently have no effect. NUM_QUEUE_SHARDS, WORKER_QUEUE_SHARD, DEFAULT_TENANT_ID and ENABLE_TENANT_ISOLATION are not read at all; the images no longer set or use them.