All configuration is via environment variables. Most settings can also be changed at runtime through the web UI (Settings page), in which case the DB-stored value takes precedence over the env var after the first change.
Unreadable values. A variable that is set but cannot be parsed (for example SENTINEL_POLL_INTERVAL=86400, or SENTINEL_WEB_ENABLED=maybe) falls back to its default, and Sentinel logs an error at start-up naming the variable, the value it could not read and the default in use. Values of tokens, passwords, secrets, keys and URLs with credentials are never logged. Booleans accept true, false, yes, no, on and off.
Saved settings win. For image backup, remove volumes and the rollback policy, a value saved on the Settings page overrides the environment variable (SENTINEL_IMAGE_BACKUP, SENTINEL_REMOVE_VOLUMES, SENTINEL_ROLLBACK_POLICY), at startup and as soon as it is saved. With nothing saved, the environment value applies. Settings shows the value in effect and whether it comes from the saved setting or the environment; GET /api/settings reports the same in its <key>_source fields.
If you still set SENTINEL_PORTAINER_URL or SENTINEL_PORTAINER_TOKEN, Sentinel ignores them and logs a warning (the Portainer connector was removed in v3.0.0).
| Variable |
Default |
Description |
SENTINEL_DOCKER_SOCK |
/var/run/docker.sock |
Path to the Docker socket |
SENTINEL_DB_PATH |
/data/sentinel.db |
Path to the BoltDB database file |
SENTINEL_LOG_JSON |
true |
Output logs as JSON. Set false for human-readable text |
SENTINEL_DEFAULT_POLICY |
manual |
Default update policy for containers without a sentinel.policy label. One of: auto, manual, pinned
|
SENTINEL_LATEST_AUTO_UPDATE |
false |
Auto-update containers using :latest tag regardless of default policy |
SENTINEL_IMAGE_CLEANUP |
true |
Remove old images after successful updates |
SENTINEL_IMAGE_BACKUP |
false |
Tag old images before removal for rollback recovery. A value saved on the Settings page overrides this |
SENTINEL_SHOW_STOPPED |
false |
Include stopped containers in the dashboard |
SENTINEL_HISTORY_RETENTION_DAYS |
90 |
Days of update history and activity log to keep. 0 keeps everything. Records of applied updates and rollbacks are never pruned. Pruning runs daily and at start-up. A value saved in Settings > System Settings (history_retention_days) wins |
SENTINEL_REMOVE_VOLUMES |
false |
Works like docker compose up -V: the updated container starts on fresh, empty anonymous volumes, and the old ones are deleted with the old container once the new one passes validation. Off keeps the old anonymous volumes and their data. Named volumes and bind mounts are never touched. A value saved on the Settings page overrides this. For agents, the server's value is sent only with Remove volumes on agents too. Agents read their own SENTINEL_REMOVE_VOLUMES; the server's setting does not reach them |
SENTINEL_SELF_CONTAINER |
(empty) |
Name or ID of this Sentinel container. Needed only when Sentinel cannot read its own container ID from the system (for example a custom hostname on a runtime that hides /proc/self/mountinfo and /proc/self/cgroup). Checked against the Docker API: the container must exist and carry sentinel.self=true, or self-update is refused with an error naming the variable |
SENTINEL_DEPS |
true |
Dependency-aware updates (respects container links and depends_on ordering). Compose depends_on dependents are restarted after their dependency is updated only when the entry has restart: true
|
SENTINEL_HOST |
(auto-detected) |
Docker host IP or hostname, used for port links in the dashboard |
| Variable |
Default |
Description |
SENTINEL_POLL_INTERVAL |
6h |
How often to scan for updates (Go duration: 30m, 1h, 6h) |
SENTINEL_GRACE_PERIOD |
30s |
Wait time after starting a new container before health-checking. Also read by agents, and a container's sentinel.grace-period label wins |
SENTINEL_SCHEDULE |
(empty) |
Global cron expression for scan scheduling (overrides poll interval when set) |
SENTINEL_MAINTENANCE_WINDOW |
(empty) |
Time-range expression restricting when auto-updates can run. Daily: 02:00-06:00. Weekly: Sun 02:00-Sun 06:00. Multiple windows: comma-separated |
SENTINEL_SCAN_CONCURRENCY |
1 |
Number of parallel registry checks per scan cycle (max 50) |
SENTINEL_ROLLBACK_POLICY |
(empty) |
Policy applied to a container after automatic rollback. One of: manual, pinned, or empty (keep current). A value saved on the Settings page overrides this, including a saved "No change" |
| Variable |
Default |
Description |
SENTINEL_WEB_ENABLED |
true |
Enable the web dashboard and REST API. With false the daily digest still runs, and a fresh install skips the setup wizard and takes the SENTINEL_MODE role (server if unset). Also honoured on agents |
SENTINEL_WEB_PORT |
8080 |
Port for the web server |
| Variable |
Default |
Description |
SENTINEL_AUTH_ENABLED |
(nil; DB default: true) |
Enable authentication. When unset, uses the DB-stored value (true on fresh installs) |
SENTINEL_SESSION_EXPIRY |
720h (30 days) |
Session cookie lifetime |
SENTINEL_COOKIE_SECURE |
true |
Set the Secure flag on session cookies. Disable if not using HTTPS |
SENTINEL_TRUSTED_PROXIES |
(empty) |
Reverse proxy IPs or CIDR ranges (comma separated). When set, the client address is taken from X-Forwarded-For, so one attacker's failed logins do not block everyone behind the proxy |
SENTINEL_OIDC_LINK_EXISTING |
false |
Link unlinked non-admin accounts to a single sign-on identity by username. Skips admin accounts and accounts with 2FA or a passkey. A saved Settings toggle wins. See Authentication and Security
|
SENTINEL_OIDC_LINK_ADMIN |
(empty) |
One-shot recovery: the next SSO login with this username links that one account, admin or not. Remove it afterwards |
| Variable |
Default |
Description |
SENTINEL_TLS_CERT |
(empty) |
Path to TLS certificate PEM file |
SENTINEL_TLS_KEY |
(empty) |
Path to TLS private key PEM file |
SENTINEL_TLS_AUTO |
false |
Auto-generate a self-signed TLS certificate on startup |
Both SENTINEL_TLS_CERT and SENTINEL_TLS_KEY must be set together, or both left empty. SENTINEL_TLS_AUTO is an alternative that generates a self-signed certificate without needing files.
| Variable |
Default |
Description |
SENTINEL_WEBAUTHN_RPID |
(empty) |
Relying Party ID: the hostname with a dot (e.g. sentinel.example.com) or localhost. Required to enable passkeys. From 3.1.0 an IP address or a single-label name (sentinel) turns passkeys off at startup |
SENTINEL_WEBAUTHN_DISPLAY_NAME |
Docker-Sentinel |
Display name shown by authenticators during registration |
SENTINEL_WEBAUTHN_ORIGINS |
(empty) |
Comma-separated list of allowed origins (e.g. https://sentinel.example.com). Required when RPID is set |
All three variables must be configured to enable passkey authentication. SENTINEL_WEBAUTHN_RPID and SENTINEL_WEBAUTHN_ORIGINS must both be set or both empty.
| Variable |
Default |
Description |
SENTINEL_GOTIFY_URL |
(empty) |
Gotify server URL (e.g. https://gotify.example.com) |
SENTINEL_GOTIFY_TOKEN |
(empty) |
Gotify application token |
SENTINEL_WEBHOOK_URL |
(empty) |
Webhook endpoint URL for JSON POST notifications |
SENTINEL_WEBHOOK_HEADERS |
(empty) |
Extra headers for webhook requests, comma-separated Key:Value pairs |
Additional notification providers (Slack, Discord, Ntfy, Telegram, Pushover, Email, MQTT, Apprise) are configured through the web UI Settings page rather than environment variables.
| Variable |
Default |
Description |
SENTINEL_MODE |
(empty) |
Node role: server or agent. Empty defaults to standalone server |
SENTINEL_CLUSTER |
false |
Enable the gRPC cluster listener (server mode) |
SENTINEL_CLUSTER_PORT |
9443 |
gRPC port for cluster communication |
SENTINEL_CLUSTER_DIR |
/data/cluster |
Directory for CA and node certificates (auto-generated mTLS) |
SENTINEL_SERVER_ADDR |
(empty) |
Server gRPC address for agent enrolment (e.g. server-host:9443) |
SENTINEL_ENROLL_TOKEN |
(empty) |
One-time token for agent enrolment (generated by the server) |
SENTINEL_HOST_NAME |
(empty) |
Human-readable label for this node in the cluster dashboard |
SENTINEL_CLUSTER_ADVERTISE |
(empty) |
Extra IPs or hostnames to include as TLS certificate SANs (comma-separated). Use when the server is reachable on addresses beyond the auto-detected ones |
SENTINEL_GRACE_PERIOD_OFFLINE |
30m |
Time before an agent switches to autonomous mode when the server is unreachable |
| Variable |
Default |
Description |
SENTINEL_NPM_URL |
(empty) |
Nginx Proxy Manager API URL |
SENTINEL_NPM_EMAIL |
(empty) |
NPM login email |
SENTINEL_NPM_PASSWORD |
(empty) |
NPM login password |
Sentinel can check image signatures with cosign before an update. Choose the mode in Settings > Signature Verification: disabled, warn (log the failure and update) or enforce (refuse the update). A sentinel.verify label on a container, or on a Swarm service, wins over the global mode. A mode saved in Settings applies without a restart. Updates sent to cluster agents are checked on the server first.
Updates check the digest they pulled, in the image's own repository. The official Sentinel image does not include cosign, so mount it and set the cosign path, or leave verification disabled. With enforce and no cosign available, every update is refused and recorded as failed ("signature verification is set to enforce but cosign is not available"), a scan sends one notification for them, and start-up logs a warning. Warn mode still updates and logs each one. Settings warns when cosign is not found at the configured path.
Keyless verification checks the signer's certificate identity and OIDC issuer, so you must set the expected signer. Without them keyless checks fail.
| Variable |
Setting |
Description |
SENTINEL_COSIGN_IDENTITY |
cosign_identity |
Expected certificate identity (signer) |
SENTINEL_COSIGN_OIDC_ISSUER |
cosign_oidc_issuer |
Expected OIDC issuer |
SENTINEL_COSIGN_IDENTITY_REGEXP |
cosign_identity_regexp |
true to match both as regular expressions instead of exactly |
A saved setting wins over the variable. These apply without a restart; switching keyless on or off, the key path and the cosign path still need one.
| Variable |
Default |
Description |
SENTINEL_HOOKS |
false |
Run lifecycle hooks during updates. Hooks come from sentinel.hook.* labels or the REST API. Web UI: Settings > Scanning > Lifecycle Hooks > Lifecycle hooks
|
SENTINEL_HOOKS_WRITE_LABELS |
false |
When Sentinel recreates a container during an update, write its hooks saved through the REST API onto the new container as sentinel.hook.* labels. Web UI: Write hook labels in the same section |
A value saved with either toggle in the web UI overrides the environment variable. See Lifecycle Hooks.
| Variable |
Default |
Description |
SENTINEL_METRICS |
false |
Enable the Prometheus metrics endpoint (/metrics) |
SENTINEL_METRICS_TEXTFILE |
(empty) |
Path for node_exporter textfile collector output (writes .prom file instead of serving HTTP) |
Environment variables accepting durations use Go's time.Duration syntax:
| Suffix |
Meaning |
Example |
s |
Seconds |
30s |
m |
Minutes |
5m |
h |
Hours |
6h |
Combine as needed: 1h30m, 2h45m30s.