Configuration

Change a self-hosted pod's settings safely with synap config, and the settings you are most likely to need.

A pod's settings live in /opt/synap/deploy/.env, created by the installer with generated secrets. Change it with synap config, not with a text editor: synap config checks every value against the schema in deploy/env.schema and writes the file atomically, keeping a backup.

Change a setting

cd /opt/synap/deploy
sudo synap config set SMTP_CONNECTION_URI='smtp://user:pass@smtp.example.com:587'
sudo synap apply

synap apply recreates the running services whose configuration changed, so they read the new .env. It never deletes a volume or starts a stopped service.

synap config

Command	What it does
`synap config list`	Every key, with secrets masked.
`synap config get KEY [--reveal]`	One value, masked unless `--reveal`.
`synap config set KEY=VALUE …`	Validates every pair, then writes. Keeps `.env.bak.<timestamp>`. `--stdin` or `--from-file F` read `KEY=VALUE` lines, which keeps secret values out of your shell history.
`synap config unset KEY …`	Removes keys, with the same rules.
`synap config validate`	Checks the whole `.env` against the schema. Non-zero exit on errors.
`synap config diff [from] [to]`	Masked diff, by default from the newest backup to the current `.env`.
`synap config edit`	Opens a copy in `$EDITOR`; replaces `.env` only if the copy validates.

synap config set refuses:

keys the schema does not know (a typo, or something like PATH);
values of the wrong type (a host name with https://, a non-numeric count);
keys owned by synap update (the release and image keys);
changes to an immutable secret that already has a value, such as POSTGRES_PASSWORD or JWT_SECRET, because existing data depends on it. --force overrides this; only use it if you know the data does not depend on the old value.

Settings you are likely to change

Key	What it is
`DOMAIN`	The pod's host name. See Domains and TLS.
`PUBLIC_URL`	The pod's public origin, `https://<DOMAIN>` by default.
`POD_ADMIN_DOMAIN`, `POD_ADMIN_URL`	The admin console's host name and origin.
`LETSENCRYPT_EMAIL`	Contact email for certificates.
`SMTP_CONNECTION_URI`, `SMTP_FROM_ADDRESS`	The mail server for recovery codes and verification emails. Without them, mail is not delivered and the "Email me a code" recovery option stays hidden. The from-address must be on a domain your mail relay has verified.
`INTELLIGENCE_HUB_URL`, `INTELLIGENCE_HUB_API_KEY`	The Intelligence Service behind the pod's built-in AI features.
`CONTROL_PLANE_URL`	The Synap Control Plane this pod talks to, if any.
`SYNAP_CATALOG_SOURCE`	`off` stops the pod from fetching Synap's marketplace catalog (it otherwise reads it every 10 minutes, anonymously).
`SYNAP_UPDATE_CHANNEL`	The release channel a bare `synap update` uses: `stable` (default) or `fast`.
`BACKUP_REPOSITORY` and `BACKUP_*`	The off-host backup target. See Backups.
`PG_BACKUP_INTERVAL_SECONDS`, `PG_BACKUP_KEEP`, `PG_BACKUP_KEEP_DAILY`	Local dump schedule: every 3600 seconds, keeping the newest 6 plus one per day for 7 days, by default.
`MAX_UPLOAD_SIZE`	The largest upload the pod accepts, for example `100MB`.
`SYNAP_EDGE`	`caddy` (default) or `traefik` when another web server is in front of the pod.

The full list, with each key's type and flags, is deploy/env.schema in the deploy directory.

Connectors

Connections to outside accounts (Google, Slack, GitHub and so on) go through Nango. Who brokers them depends on two settings:

Your pod	Connections are brokered by
`CONTROL_PLANE_URL` is set	The Control Plane, with a credential it delivers to the pod. A local `NANGO_HOST` and `NANGO_SECRET_KEY` are ignored.
`CONTROL_PLANE_URL` is set and `SYNAP_CONNECTOR_BROKER=local`	Your own Nango instance, at `NANGO_HOST` with `NANGO_SECRET_KEY`.
`CONTROL_PLANE_URL` is empty	Your own Nango instance, at `NANGO_HOST` with `NANGO_SECRET_KEY`.

sudo synap config set SYNAP_CONNECTOR_BROKER=local NANGO_HOST=https://nango.example.com
printf 'NANGO_SECRET_KEY=%s\n' '<secret>' | sudo synap config set --stdin
sudo synap apply

Secrets

The installer generates every secret the pod needs (database password, JWT secret, Kratos secrets, MinIO and Typesense keys, encryption keys). synap config list and get mask them. Secrets are also included, encrypted, in the off-host backup snapshot; see Backups.

Change a settingCopy Anchor Link

synap configCopy Anchor Link

Settings you are likely to changeCopy Anchor Link

ConnectorsCopy Anchor Link

SecretsCopy Anchor Link

On this page

Change a setting

synap config

Settings you are likely to change

Connectors

Secrets