Browse the docs

Configuration

One config model: file, environment variables, and precedence.

Synapass has one configuration model across Docker, native, and desktop. Learn it once; every deployment path obeys it.

Precedence#

Lowest to highest:

  1. Built-in defaults — a config file is optional; the defaults boot.
  2. Config file — --config / SYNAPASS_CONFIG_FILE.
  3. Environment variables — SYNAPASS_* always win, which is what makes a container override of one value possible without a second file.
bash
# Inspect the resolved configuration (secrets redacted)
SYNAPASS_ADMIN_KEY=$(openssl rand -hex 24) synapass config --config config.example.yaml

Secrets are referenced, never embedded#

Every credential names an environment variable via *_env. The secret stays in your environment and out of version control — which keeps the config file safe to commit and keeps synapass config from becoming the leak.

yaml
providers:
  - name: openai-prod
    kind: openai
    base_url: https://api.openai.com/v1
    api_key_env: OPENAI_API_KEY   # the name, not the value
env
# .env — never committed
SYNAPASS_ADMIN_KEY=<generated with openssl rand -hex 24>
OPENAI_API_KEY=<your provider key>
ANTHROPIC_API_KEY=<your provider key>

An inline api_key on a provider write is discarded by the gateway. If a secret appears where a reference belongs, it is dropped rather than stored.

The main sections#

config.example.yaml is the annotated reference. The sections you will touch most:

SectionWhat it controls
app.environmentdevelopment / staging / production. Production tightens validation: an admin surface without a bootstrap key refuses to start, and a CORS wildcard is rejected.
app.default_tenant_*The tenant seeded on first boot so a fresh install is usable.
app.bootstrap_from_configApply the providers/policies in the file on every startup, upserting by name. The database is the runtime source of truth afterwards.
http.addrBind address. Use :8080 in containers; bind 127.0.0.1:8080 on a host behind a reverse proxy.
http.cors_allowed_originsThe dashboard's origin. A wildcard is refused in production.
database.*PostgreSQL connection — discrete fields or a full dsn. auto_migrate: true is convenient for self-hosting; under strict change control, set it false and run synapass migrate as a release step.
redis.*Redis connection. key_prefix namespaces every key so one Redis can serve several deployments.
auth.*Header name, minimum key length, and validated-key cache TTL.

Durations accept a string ("30s", "5m", "2h") or a bare number of seconds.

Environment variable overrides#

Any file value can be overridden without editing the file. The Docker path uses this for the two values operators change most:

env
# Move the host port when 8080 is taken
GATEWAY_PORT=18080
NEXT_PUBLIC_SYNAPASS_API_URL=http://localhost:18080

First-run checklist#

  1. Copy .env.example to .env (Docker) or the systemd drop-in (native).
  2. Generate SYNAPASS_ADMIN_KEY with openssl rand -hex 24.
  3. Add at least one provider key (OPENAI_API_KEY / ANTHROPIC_API_KEY).
  4. Start the stack and check /ready — it only reports ready after migrations and catalogue seeding finish.
  5. Create the console administrator in the dashboard; there are no defaults.

Related#