Configure Sift

Sift’s deployment settings are environment variables in one file, .env, beside docker-compose.yml. There is no other configuration file. This page explains how a setting reaches the services, when a change takes effect, and which settings most deployments change. Every variable, with its default, is in the configuration reference.

Three places settings live

Where	What	Who changes it
`.env` on the host	How the deployment runs: secrets, ports, the Kindo API address, retention, logging, metrics, the decision model switch.	Whoever runs the stack.
Administration, in the console	The Kindo connection and its model, users, which recipes new filters may use, webhook endpoints.	An admin.
A filter’s own settings	Its source, poll interval, pipeline stages, leak-through rate, trigger ceiling, retrain schedule and the rest.	An operator or admin, per filter. See Change a filter’s settings.

Nothing in .env changes one filter, and nothing in a filter changes the deployment.

How `.env` reaches the services

make init writes .env from .env.example, with mode 600, and generates three secrets: SIFT_SECRET_KEY, POSTGRES_PASSWORD and SEAWEEDFS_SECRET_KEY. It never overwrites an existing .env, so running it again is safe.

.env is then read two ways:

By the backend containers. It is the env_file of sift-api, the three workers and sift-beat, so every SIFT_* line reaches all five. Any setting the server defines works this way, written as SIFT_ plus the setting’s name in capitals, whether or not .env.example lists it.
By Compose itself, to fill in the compose file: the datastore credentials (POSTGRES_*, SEAWEEDFS_*), the ports (SIFT_WEB_PORT, SIFT_HTTPS_PORT), the certificate directory (SIFT_TLS_DIR), the image variant (SIFT_EXTRAS) and COMPOSE_FILE.

A setting not in .env takes Sift’s built-in default; the compose file does not repeat the defaults.

When a change takes effect

Settings are read when a container starts. After editing .env, apply it with:

make up

That runs docker compose up -d, which recreates every container whose configuration changed. docker compose restart does not re-read .env, so a restarted container keeps its old settings. make smoke reports any SIFT_* setting in .env that sift-api does not see, and asks you to recreate it.

Two settings behave differently:

POSTGRES_PASSWORD is read by Postgres only when its volume is first created. Changing it later also needs ALTER USER inside the database, or the services can no longer connect.
SEAWEEDFS_SECRET_KEY is read on every start. Changing it is a restart, and the old key stops working at once.

Settings Sift refuses at start

Some values stop every backend container from starting, with an error that names the setting and never its value:

Refused	When
A missing `SIFT_SECRET_KEY`	Always. `docker compose up` itself fails with set SIFT_SECRET_KEY in .env.
A published or weak credential	With `SIFT_ENVIRONMENT=production`: see the list in Deploy for production.
`SIFT_METRICS_TOKEN` shorter than 32 characters	Always. Unset means no metrics endpoint.
`SIFT_SAVINGS_WARN` below `SIFT_SAVINGS_FLOOR`	Always.
`SIFT_CONSOLE_URL` that is not an absolute `http://` or `https://` address	Always.
`SIFT_WEBHOOK_PRIVATE_NETWORKS` with a range outside the private or CGNAT ranges	Always.
`SIFT_JEV_ENABLED=true` without `SIFT_JEV_API_KEY`	Always.

Settings most deployments change

Setting	Default	Why you would change it
`SIFT_ENVIRONMENT`	`development`	`production` for any real deployment. See Deploy for production.
`SIFT_DEFAULT_ADMIN_PASSWORD`	`admin`	Set before the first start. It seeds the first admin account only when that account does not exist; it never resets a password.
`SIFT_DEFAULT_ADMIN_USERNAME`	`admin`	To name the first admin account differently.
`SIFT_WEB_PORT`	`8080`	The host port for the console and API.
`COMPOSE_FILE`	unset	`docker-compose.yml:docker-compose.tls.yml` to make the TLS overlay the default.
`SIFT_TRUSTED_PROXY_HOPS`	`1`	`2` behind a load balancer that appends to `X-Forwarded-For`; `0` if nothing proxies the API.
`SIFT_CONSOLE_URL`	unset	The console’s address as people reach it, for links in alerts.
`SIFT_DEPLOYMENT_NAME`	unset	Names this deployment in every alert, for a receiver that hears from several.
`SIFT_METRICS_TOKEN`	unset	Turns on `/api/metrics`. Generate one with `openssl rand -hex 32`.
`SIFT_ASSUMED_COST_PER_AGENT_RUN_USD`	unset	What one agent run costs you. Unset, Sift reports runs avoided and says the spend is unknown rather than inventing a price.
`SIFT_AGENT_DEFAULT_RUNS_PER_HOUR`	unset	How many runs an hour one agent can take, when a filter does not say. Unset, half of what the Kindo rate limit allows. Sift sizes its suggestions for a big stream from it.
`SIFT_EXTRAS`	unset	`setfit` to build and run the image that can train the Text analysis (small sample) recipe.
`SIFT_WEBHOOK_PRIVATE_NETWORKS`	unset	Private or CGNAT ranges an on-premises webhook receiver lives in, as comma-separated CIDRs.
`SIFT_MODEL_FETCH_ON_START`	`true`	`false` on a host without internet access. See Install without internet access.
`SIFT_SESSION_TTL_HOURS`	`12`	How long a session lasts if nobody signs it out.
`SIFT_LOG_FORMAT`	`json`	`console` for human-readable logs.
`SIFT_EVENT_PAYLOAD_RETENTION_DAYS` and the other retention windows	30, 400, 14 days	How long event content and records are kept. See Security and data handling.

The decision model is switched on here too (SIFT_JEV_ENABLED with SIFT_JEV_API_KEY), and is off by default. See Decision model settings.