# The configuration file

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

Sentinel reads all server settings from one TOML file. Changes take effect after a restart, and unknown keys stop the server from starting. Tenant settings, such as accounts and security groups, are managed at runtime instead; see [Accounts & policies](/docs/sentinel/v2/policies/).

## Server settings and tenant settings

Sentinel has two places to configure, owned by different people:

| | Server settings | Tenant settings |
| --- | --- | --- |
| What | Listeners, database, KV store, secrets, license, sign-in methods, remote lists, alerts delivery, storage, telemetry | Accounts, users, roles, API keys, security groups and their rules, training data, threat entries |
| Where | `sentinel.toml` | Admin UI or the `/v2` API |
| Who | The operator who runs Sentinel | Root users and account admins |
| When it applies | At the next restart | Immediately, on every replica |

This section covers server settings. Every key, its type, and its default are listed in the [Configuration reference](/docs/sentinel/v2/reference/configuration/).

## Where the file is loaded from

Sentinel looks for its configuration in this order:

1. The path given with `--config` (or `-c`). If that file can't be read, startup fails.
2. Otherwise, `sentinel.toml` in the working directory, if it exists.
3. Otherwise, Sentinel starts with the built-in defaults for every key.

Sentinel ships as the container image `ghcr.io/altcha-org/sentinel`, whose entrypoint is the `altcha-sentinel` binary, so arguments after the image name go to it. To keep the file outside the working directory, mount it anywhere and pass the path:

```bash
docker run -d --name sentinel -p 3000:3000 \
-v "$PWD/sentinel.toml:/etc/sentinel/sentinel.toml:ro" \
-v "$PWD/secrets:/run/secrets:ro" \
ghcr.io/altcha-org/sentinel:2.0.0-beta.1 --config /etc/sentinel/sentinel.toml
```

Every key is optional, so the file only needs the settings you change. The same `--config` flag applies to the CLI commands that read the configuration (`doctor`, `healthcheck`, `license request`, `migrate`, `schema sql`); see the [CLI reference](/docs/sentinel/v2/reference/cli/).

> **Tip:**
>
> The image's working directory is `/home/nonroot`, so a file mounted at `/home/nonroot/sentinel.toml` is read without `--config`. The image's built-in health check reads only that path; with `--config`, pass the same flag to your own health check. See [Docker](/docs/sentinel/v2/install/docker/).

## Environment variables and secret files

Any string value can contain `${…}` references. Sentinel expands them once at startup, after parsing the TOML:

| Syntax | Expands to |
| --- | --- |
| `"${VAR}"` | The value of environment variable `VAR`. An unset or empty variable expands to an empty string. |
| `"${VAR:-fallback}"` | The value of `VAR`, or `fallback` when `VAR` is unset or empty. |
| `"${file:/path}"` | The contents of the file at `/path`, with one trailing newline (`\n` or `\r\n`) removed. A missing file stops startup. |
| `"${file:/path:-fallback}"` | The file contents, or `fallback` when the file is missing or empty. |
| `'\${VAR}'` | The literal text `${VAR}`, not expanded. |

A few rules follow from how expansion works:

- **Empty means unset.** A string that is empty, literally or after expansion, is removed before the configuration is checked, so the key takes its default. `jwt_secret = "${JWT_SECRET}"` with `JWT_SECRET` unset behaves as if the key were missing.
- **Only strings are expanded.** Numbers and booleans are literal. `port = "${PORT:-3000}"` is a string, and Sentinel rejects it with ``invalid type: string "3000", expected u16``.
- **References can sit inside a value**, for example a password inside a connection string: `url = "postgres://app:${DB_PASSWORD}@db:5432/sentinel"`.
- **Variable names** must look like `[A-Za-z_][A-Za-z0-9_]*`. Anything else, such as `${JWT-SECRET}`, stops startup with `invalid variable name`. There is no nesting: the first `}` closes the reference.
- **Escaping.** The backslash must reach Sentinel, so use a single-quoted TOML string (`'\${VAR}'`) or escape it in a double-quoted one (`"\\${VAR}"`).

This example reads the root password from the environment with a fallback, and the challenge secret from a mounted file:

```toml
[bootstrap]
root_password = "${ROOT_PASSWORD:-change-me-on-first-login}"

[secrets]
altcha_hmac_secret = "${file:/run/secrets/altcha_hmac_secret}"
jwt_secret         = "${JWT_SECRET}"
```

If a reference can't be resolved, the error names the key but never prints its value:

```text
Error: loading config sentinel.toml

Caused by:
0: config key `secrets.altcha_hmac_secret`
1: config: reading secret file '/run/secrets/altcha_hmac_secret': No such file or directory (os error 2)
```

Keep every secret in an environment variable or a file, never as a literal in `sentinel.toml`. Which values are secrets, and what rotating them breaks, is covered in [Server secrets](/docs/sentinel/v2/configure/secrets/).

## Unknown keys and invalid values stop startup

Sentinel rejects any key it doesn't recognize, in every section. A typo fails loudly instead of being silently ignored. For example, `prot = 3000` under `[server]`:

```text
Error: loading config sentinel.toml

Caused by:
unknown field `prot`, expected one of `host`, `port`, `trusted_proxies`, `client_ip_header`, `forwarded_host_header`, `base_url`, `v1_compat`, `public_api`, `admin_ui`
in `server`
```

After loading, Sentinel also checks values and combinations of keys (ranges, required companions, mutually exclusive keys) before it opens any connection. The process exits with code `1` and the reason on stderr.

TOML syntax errors report the line and column but not the source line, because it might contain a secret.

## Changes need a restart

Sentinel reads the file only at startup. There is no hot reload: edit the file, then restart the process (or roll your replicas). The same applies to files the configuration points to, such as `tls` certificates: a renewed certificate takes effect at the next restart. In a cluster, give every replica the same file; see [Clustering & high availability](/docs/sentinel/v2/operations/clustering/).

## Validate the file

Run `doctor --config-only` to check a file without starting the server. It loads and expands the file and runs the same checks as startup, but opens no connections, so it suits CI and pre-deploy hooks. Run it in a one-off container with the same mounts as the server:

```bash
docker run --rm \
-v "$PWD/sentinel.toml:/etc/sentinel/sentinel.toml:ro" \
-v "$PWD/secrets:/run/secrets:ro" \
ghcr.io/altcha-org/sentinel:2.0.0-beta.1 --config /etc/sentinel/sentinel.toml doctor --config-only
```

```text
altcha-sentinel 2.0.0-beta.1 doctor, config: /etc/sentinel/sentinel.toml

config
ok    config.file   Loaded /etc/sentinel/sentinel.toml.
ok    config.valid  The configuration passes the startup checks.

2 ok, 0 warn, 0 fail, 0 skipped in 2 ms
```

A failing check prints `FAIL` with the error and a hint, and the command exits with `1`:

```text
config
ok    config.file             Loaded sentinel.toml.
FAIL  config.valid (license)  [license] file and key are mutually exclusive.
                            hint: Fix this setting; the server does not start with it.
```

Run the check with the same environment variables (`-e` or `--env-file`) and mounted files as the server, because `${…}` references are expanded and the `tls` certificate files of enabled listeners are loaded during validation. Without `--config-only`, `doctor` also checks storage, network access, and the rest of the host, so run the full check inside the running container (`docker exec sentinel /usr/local/bin/altcha-sentinel --config /etc/sentinel/sentinel.toml doctor`); see [Troubleshooting](/docs/sentinel/v2/operations/troubleshooting/) and the [CLI reference](/docs/sentinel/v2/reference/cli/).

## The data directory

`data_dir` (default `./data`, relative to the working directory) holds local state. Sentinel creates it at startup when it uses the embedded SQLite database. A single node with default settings ends up with:

```text
data/
├── sentinel.db          # embedded SQLite database (plus -wal and -shm files in WAL mode)
├── secrets.json         # generated secrets, only when some [secrets] keys are unset
├── remote-files/        # downloaded lists and their .meta.json state
├── threats/             # one SQLite index per threat source
└── eml/                 # index of malicious attachment hashes
```

- `sentinel.db` exists only while `[database] url` is unset. With an external database, nothing is stored there.
- `secrets.json` is written only with embedded SQLite, for the secrets you didn't set. Back it up: losing it invalidates sessions, challenges, and stored encrypted values. See [Server secrets](/docs/sentinel/v2/configure/secrets/).
- `remote-files/`, `threats/`, and `eml/` are caches that Sentinel rebuilds from their sources. See [Remote files & data sources](/docs/sentinel/v2/configure/remote-files/).
- Relative paths of local MaxMind or IPinfo databases in `[[ip_resolver.providers]]` resolve inside `data_dir`. See [IP resolvers](/docs/sentinel/v2/configure/ip-resolvers/).

Mount `data_dir` on a persistent volume. If that volume is network storage (AWS EFS, NFS, or an SMB share such as Azure Files), set `[database] sqlite_journal_mode = "delete"`; see [SQLite on network storage](/docs/sentinel/v2/configure/databases/#sqlite-on-network-storage). See [Top level](/docs/sentinel/v2/reference/configuration/#top-level) in the reference.

## A production starting point

This file runs one replica with PostgreSQL and Redis, the admin UI behind a TLS proxy, and every secret read from a mounted file. Adjust the hosts and paths, then add the sections you need. Without a proxy, set `tls` on each listener you expose instead; see [Listener TLS](/docs/sentinel/v2/reference/configuration/#listener-tls).

```toml
data_dir = "/home/nonroot/data"

[server]
host     = "0.0.0.0"
port     = 3000
base_url = "https://sentinel.example.com"
trusted_proxies = ["10.0.0.0/8"]   # your reverse proxy or load balancer

[server.admin_ui]
enabled  = true
host     = "0.0.0.0"               # default 127.0.0.1; expose only behind HTTPS
base_url = "https://admin.sentinel.example.com"

[database]
url = "postgres://sentinel:${file:/run/secrets/db_password}@db:5432/sentinel"

[redis]
nodes = ["redis://:${file:/run/secrets/redis_password}@redis:6379"]

[secrets]
jwt_secret         = "${file:/run/secrets/jwt_secret}"
altcha_hmac_secret = "${file:/run/secrets/altcha_hmac_secret}"
encryption_key     = "${file:/run/secrets/encryption_key}"

[license]
key = "${file:/run/secrets/sentinel_license_key}"

[bootstrap]
root_password = "${file:/run/secrets/root_password}"
```

What each section does and where to read more:

| Section | Read more |
| --- | --- |
| `[server]`, `[server.admin_ui]` | [Listeners & reverse proxy](/docs/sentinel/v2/configure/listeners/), reference [`[server]`](/docs/sentinel/v2/reference/configuration/#server) and [`[server.admin_ui]`](/docs/sentinel/v2/reference/configuration/#serveradmin_ui) |
| `[database]`, `[redis]` | [Databases & KV store](/docs/sentinel/v2/configure/databases/), reference [`[database]`](/docs/sentinel/v2/reference/configuration/#database) and [`[redis]`](/docs/sentinel/v2/reference/configuration/#redis) |
| `[secrets]`, `[bootstrap]` | [Server secrets](/docs/sentinel/v2/configure/secrets/), reference [`[secrets]`](/docs/sentinel/v2/reference/configuration/#secrets) and [`[bootstrap]`](/docs/sentinel/v2/reference/configuration/#bootstrap) |
| `[license]` | [Configure the license](/docs/sentinel/v2/configure/licensing/), reference [`[license]`](/docs/sentinel/v2/reference/configuration/#license) |

<Callout type="note" title="License required">

PostgreSQL needs the <code>exotdb.backend.postgres</code> license feature. Without it, Sentinel starts but answers most `/v2` requests with `403 BACKEND_NOT_LICENSED`. See [Plans & Licensing](/docs/sentinel/v2/plans/).

What a production deployment needs beyond this file (replica count, backups, sizing) is listed in [Install](/docs/sentinel/v2/install/). Before going live, work through the [Production checklist](/docs/sentinel/v2/security/production-checklist/).

## In this section

- [Configure the license](/docs/sentinel/v2/configure/licensing/): Install an offline license file or an online license key, check the license status, and understand instance slots.
- [Listeners & reverse proxy](/docs/sentinel/v2/configure/listeners/): Configure Sentinel's main, public widget, admin UI, and Prometheus listeners, its base URL, trusted proxies, and client IP headers.
- [Databases & KV store](/docs/sentinel/v2/configure/databases/): Choose and configure Sentinel's database (SQLite, PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, or remote ExotDB) and its KV store.
- [Server secrets](/docs/sentinel/v2/configure/secrets/): Set the JWT, HMAC, encryption, and VAPID secrets and the bootstrap root password, and understand what rotating them breaks.
- [IP resolvers](/docs/sentinel/v2/configure/ip-resolvers/): Configure the providers Sentinel uses to add location and network data to client IP addresses.
- [Object storage](/docs/sentinel/v2/configure/storage/): Configure S3-compatible or Azure Blob storage for email attachment uploads and stored snapshots.
- [Remote files & data sources](/docs/sentinel/v2/configure/remote-files/): Which lists and databases Sentinel downloads, where they come from, how often they refresh, and how to manage them.
- [Outbound proxy & air-gapped deployments](/docs/sentinel/v2/configure/air-gapped/): Run Sentinel behind an outbound HTTP proxy or with no internet access: required hosts, mirrored lists, and offline licensing.
