Install Sentinel
Sentinel runs as a container image for amd64 and arm64. This page lists what every production install needs; the platform guides link back here instead of repeating it.
To try Sentinel on your machine first, follow Get started.
Requirements at a glance
| Requirement | Single instance | Several replicas |
|---|---|---|
| Container runtime | Docker or any OCI runtime | Kubernetes, ECS, App Service, or Compose |
| License | Required to serve challenges, verification, and feature endpoints | Required; its instances limit caps the replica count |
| Configuration | One sentinel.toml | The same sentinel.toml on every replica |
| Database | Embedded SQLite in the data volume (default) | A shared external database |
| Redis | Not needed | Required |
| Secrets | Generated into the data volume, or set explicitly | Set explicitly, identical on every replica |
| Persistent volume | Required for /home/nonroot/data | Recommended (remote files and caches) |
| HTTPS | tls on the exposed listeners, or a TLS-terminating proxy in front | A TLS-terminating load balancer, or tls on every replica |
Sizing
CPU is mostly spent deriving proof-of-work challenges and classifying text; memory depends on the features you enable.
| Deployment | CPU | Memory |
|---|---|---|
| Evaluation, low traffic | 1 vCPU | 512 MB |
| Production, per replica | 2 vCPU or more, compute-optimized | 1 GB or more |
Use compute-optimized instances in production, such as AWS C-family (c7a, c7i, c7g), Google Cloud C-series (c3, c3d, c4), or Azure F-series. Avoid burstable instances such as AWS t3: their CPUs are slower, and they're throttled to a baseline once their CPU credits run out.
Up to [pow] cpus challenges are derived at once, and the default is half the available CPUs. If challenges make up most of your traffic, set it to the vCPU count.
Add memory for these features:
- Local similarity model (
[similarity] provider = "local"): the model and tokenizer are about 135 MB to download, and each ONNX session ([similarity.local] sessions, default1) holds its own copy of the model in memory. - Memory-hard proof of work (
pow.algorithmset toARGON2IDorSCRYPTin a security group): every challenge derivation allocates its memory cost (default65536KiB forARGON2ID, capped by[pow] max_memory_cost). Up to[pow] cpusderivations run at once (default: half the available CPUs).
For a sense of throughput, a benchmark on an AWS c7a.medium (1 vCPU, 2 GiB) with an external Redis, with the load generator on a separate machine sending 16 concurrent requests, measured:
| Endpoint | Requests per second | p99 latency |
|---|---|---|
GET /v2/challenge (default PBKDF2 cost) | about 1,500 | 11 ms |
POST /v2/verify | about 4,400 | 5.1 ms |
POST /v2/verify with fields classified | about 1,000 | 26 ms |
POST /v2/verify/signature | about 6,900 | 3.3 ms |
POST /v2/classifier | about 900 | 26 ms |
Measure your own traffic mix before you size a cluster. Each replica reports its CPU and memory use; see Monitoring and Performance.
Database size
Accounts, users, API keys, security groups, and threat sources take a few megabytes at most. The database grows with request logs, their hourly statistics, and, without Redis, the built-in KV store:
| Data | Written when | Kept for | Space per row, SQLite / PostgreSQL |
|---|---|---|---|
| Request logs | Every request of an API key whose requestLogging is verification or all (default none); not with ClickHouse | [request_logs] retention, default 72h | about 370 B / 400 B |
| Hourly request statistics | One row per API key and UTC hour with logged requests | Indefinitely | about 1 KB, more with many countries, referrers, and rules |
| Built-in KV store | Without [redis] nodes, the same entries as in the Redis table | As in Redis | about 180 B / 300 B |
| Audit logs and alerts | Sign-ins, management changes, raised alerts | [audit_logs] retention and [alerts] retention, default 90d | small |
Sizes include indexes. They were measured on SQLite and PostgreSQL 18 with logs of GET /v2/challenge, POST /v2/verify with two classified fields, and POST /v2/verify/signature.
Request logs usually dominate. Estimate them as average logged requests per second × retention in seconds × 400 B. With requestLogging set to all, one form submission logs a challenge and a verification on the widget key, plus a signature check if your backend's key logs too.
| Average logged requests per second | Retention 72h (default) | Retention 7d |
|---|---|---|
| 1 | about 100 MB | about 250 MB |
| 10 | about 1 GB | about 2.4 GB |
| 100 | about 10 GB | about 24 GB |
Hourly statistics add about 10 MB per API key per year of continuous traffic. For high volumes or long retention, store request logs in ClickHouse, which keeps both the raw logs and the statistics out of the main database.
Without Redis, every /v2 request also writes rate-limit counters to the database, and every verification and signature check writes a replay claim, so the database takes writes on every request. Use Redis or Valkey to move that load off the database; see Built-in KV store.
Deleted rows free space for new rows, but embedded SQLite doesn't shrink its file. Whatever the backend, the data volume also holds the threat-list indexes and downloaded remote files, about 230 MB with the default sources. Give it at least 1 GB, plus your database estimate with embedded SQLite.
Redis or Valkey
An external KV store ([redis] nodes or [redis.sentinel]) holds the short-lived state that every replica must share, and carries messages between replicas. Every key Sentinel writes has an expiry, so memory depends on your request rate and how long each entry lives, not on the size of your database.
| Data | Written by | Kept for | Memory per entry |
|---|---|---|---|
Replay protection: one claim per verified challenge, and one per payload checked by POST /v2/verify/signature | POST /v2/verify, POST /v2/verify/signature | Until the challenge expires: pow.expires, default 20m, at most 24h | about 130 B |
| Rate-limit counters | Every /v2 request ([rate_limit] global), security-group rateLimit.limits, classifier and audio limits | One window of the limit | about 150 B per client and limit |
| Penalties | Failed verifications, rate-limit pressure, penalty.add rules, header entropy | [penalty] ttl after the last increase, default 30m | about 150 B per account and client IP |
| Header entropy | GET /v2/challenge and GET /v2/inspect, when headerEntropy.limit is set | The headerEntropy.limit window | up to about 2 KB per client IP |
| HIS replay detection | POST /v2/challenge, when his.mode isn't off | 10 minutes for human-like interaction, up to his.hashTtl (default 12h) for bot-like interaction | about 3 KB per challenge |
| Campaign detection | Each classified text of at least [similarity.campaign] min_chars (default 30) characters | [similarity.campaign] window, default 1h | about 1 KB per text |
| Sign-in and alert state | Logins, OTP, passkeys, step-up, alert evaluation, threat signals | Minutes to hours | negligible |
Pub/sub carries replica status, API-key and security-group change notices, and threat-list updates between replicas; it stores nothing. The sizes above were measured on Redis 7.4 and Valkey 8.1 with the default key_prefix; Valkey needs the same or up to about 20% less.
Replay claims usually dominate. Estimate them as peak verifications per second × pow.expires in seconds × 130 B, doubled when your backend calls POST /v2/verify/signature for every submission. Add HIS at about 3 KB per scored challenge for as long as it is kept. Rate-limit counters are small in comparison: 60,000 distinct client IPs per minute under the default 100/1m global limit take about 9 MB.
| Peak verifications per second | Without HIS | With HIS (about 15 minutes kept) |
|---|---|---|
| 10 | about 3 MB; give it 256 MB | about 30 MB; give it 256 MB |
| 100 | about 30 MB; give it 256 MB | about 300 MB; give it 1 GB |
| 1,000 | about 310 MB; give it 1 GB | about 3 GB; give it 8 GB |
The table assumes the default pow.expires of 20m and a POST /v2/verify/signature call per submission. The suggested sizes are about twice the estimate, rounded up, which leaves room for allocator fragmentation, replication buffers, and the copy-on-write memory of RDB snapshots and AOF rewrites. Don't go below 256 MB.
These settings raise memory use:
- A long
pow.expires. Claims live as long as the challenge: at 100 verifications per second, a24hexpiry keeps about 2.2 GB of claims. - HIS under a sustained attack. The more bot-like a payload scores, the longer it is kept, up to
his.hashTtl. Set a lowerhis.hashTtlin the security group's rules to cap it. - Sliding-window limits. A limit with
(sliding)stores every request in the window: about 30 B per request, rising to about 100 B per request above 128 requests in one window. A1000/1h(sliding)limit can take about 100 KB per client. Prefer fixed-window limits for large counts.
Set maxmemory to the size you provision and maxmemory-policy to noeviction. Evicting a replay claim would let its solution be accepted again, and evicting a counter resets a rate limit. With noeviction, a full store rejects writes instead: the widget endpoints keep working with per-replica fallbacks (see Clustering), but sign-in, OTP, and passkeys fail until memory frees up. Alert on used_memory well before the limit.
Persistence is optional. Without it, a restart of Redis forgets replay claims, rate-limit counters, and penalties, so a solution verified before the restart can be replayed until its challenge expires. Enable AOF (appendonly yes) if that window matters to you.
Container image
The image is published to the GitHub Container Registry as ghcr.io/altcha-org/sentinel. It is a multi-arch image for linux/amd64 and linux/arm64; your runtime pulls the right one automatically.
| Tag | Contents |
|---|---|
2.0.0-beta.x (e.g. 2.0.0-beta.1) | A v2 beta release, with every database backend except Oracle. Pin an exact version. |
2.0.0-beta.x-oracle (e.g. 2.0.0-beta.1-oracle) | The same release plus the Oracle Instant Client, which the Oracle backend needs. |
Both images contain the same binary. Use the -oracle image only with an Oracle database; it is larger.
The container runs as the non-root user 65532:65532 with working directory /home/nonroot. Relative paths in the configuration resolve against the working directory, so these are the paths inside the image:
| Path | Purpose |
|---|---|
/usr/local/bin/altcha-sentinel | The binary, and the image's entrypoint. Arguments you pass to the container go to it (e.g. doctor). |
/home/nonroot/sentinel.toml | The configuration file read by default. Mount yours here, read-only, or pass --config <path>. |
/home/nonroot/data | data_dir: the embedded database, generated secrets, and downloaded remote files. Owned by 65532; mount a persistent volume here. |
/home/nonroot/assets/tts | Voices for code-challenge audio ([code_challenge] tts_dir), shipped in the image. |
/opt/oracle/instantclient | Oracle Instant Client, in the -oracle image only. |
The admin UI is compiled into the binary, so the image has no static files to serve and [server.admin_ui] dir stays unset. The image contains no shell tools such as curl or wget; use the built-in altcha-sentinel healthcheck for health checks. Its HEALTHCHECK runs it every 10 s against ./sentinel.toml.
Ports
Each listener has its own port. Only the main API listener is on by default.
| Listener | Config section | Default port | Default host | Enabled by default |
|---|---|---|---|---|
Main API (every /v2 route) | [server] | 3000 | 0.0.0.0 | Yes |
| Prometheus metrics | [prometheus] | 3001 | 127.0.0.1 | No |
Admin UI (web app plus /v2) | [server.admin_ui] | 3002 | 127.0.0.1 | No |
| Public widget API | [server.public_api] | 3003 | 0.0.0.0 | No |
Listeners that default to 127.0.0.1 are unreachable from outside a container. Set their host to "0.0.0.0" to publish them, and restrict access with a firewall, allowed_ips, or your proxy. See Listeners & reverse proxy for when to split traffic across listeners.
Production essentials
Every production install needs the four items below. Set them in sentinel.toml; the platform guides show where the file and secrets come from on each platform.
License
Without an active license, Sentinel starts and you can sign in, but GET /v2/challenge, POST /v2/verify, and the feature endpoints answer 403 LICENSE_NOT_ACTIVE. Without a usable license, Sentinel also runs on the baseline: embedded SQLite only, 3 instances, 1 account, 1 user, 1 API key, and 1 security group.
Install the license in the configuration file, either as an activation key or as a signed license file. The license can't be set in the admin UI.
[license]
key = "${file:/run/secrets/sentinel_license_key}" # SENT-… activation key; or file = "<path>" for an offline license fileTo get a trial license, register at cloud.altcha.org and create a Sentinel V2 trial license in the Licenses section. See Licensing for activation, offline files, and instance slots, and Plans & Licensing for what each plan includes.
Secrets
Sentinel signs admin sessions and the admin sign-in challenge, and encrypts stored API key and TOTP secrets, with three keys in [secrets]. With embedded SQLite and no keys set, it generates them into <data_dir>/secrets.json. With any other database, or with more than one replica, set all three yourself; Sentinel refuses to start when one is missing. Every replica must use the same values.
[secrets]
jwt_secret = "${file:/run/secrets/jwt_secret}" # at least 24 characters
altcha_hmac_secret = "${file:/run/secrets/altcha_hmac_secret}" # at least 24 characters
encryption_key = "${file:/run/secrets/encryption_key}" # 64 hex charactersGenerate the values with, for example, openssl rand -hex 32. Keep secrets out of the TOML file: reference a mounted file with ${file:…} or an environment variable with ${VAR}.
See Server secrets and [secrets].
Database
The database is the source of truth for accounts, users, API keys, security groups, and logs. By default Sentinel uses embedded SQLite at <data_dir>/sentinel.db, which suits a single instance with a persistent volume. If that volume is network storage, such as AWS EFS, NFS, or Azure Files, set [database] sqlite_journal_mode = "delete"; see SQLite on network storage.
| Backend | Supported versions | [database] url scheme | Image |
|---|---|---|---|
| SQLite (embedded, default) | Bundled (SQLite 3.54.1) | sqlite: | All |
| PostgreSQL | 16 or later | postgres:// | All |
| MySQL | 8.0.13 or later | mysql:// | All |
| MariaDB | 11.4 LTS or later | mariadb:// | All |
| Microsoft SQL Server | 2022 or later | mssql:// | All |
| Oracle | 21c or later | oracle:// | -oracle image |
| ExotDB server | — | http(s):// | All |
SQLite is compiled into Sentinel, so the host's SQLite version doesn't matter. MariaDB is the only backend whose version is checked: Sentinel refuses to start on MariaDB older than 11.4, on a MariaDB server behind a mysql:// URL, and on a MySQL server behind a mariadb:// URL. Older versions of the other backends (PostgreSQL before 16, SQL Server 2016–2019, Oracle 19c) aren't tested and aren't supported.
Backends other than SQLite need the matching exotdb.backend.<kind> license feature. Use an external database when you run more than one replica. Each replica opens up to [database] pool_max connections (default 20), so keep pool_max × replicas below your database's connection limit; see [database] for the pool settings. Sentinel creates and upgrades its tables at startup, so its database account needs the right to create tables, unless a database administrator applies the migrations with [database] auto_migrate = false; see Schema migrations. TLS options for the database go in the URL; see Database TLS. If your database, Redis, or other services use certificates from a private CA, add it to the top-level tls_extra_ca_certs.
[database]
url = "postgres://sentinel:${DB_PASSWORD}@db.internal:5432/sentinel"See Databases for connection details per backend.
Redis
Sentinel keeps rate-limit counters, penalties, replay protection, and replica messaging in a KV store. With [redis] nodes empty, it uses a built-in store on its own database, which works for a single instance only. As an external store, use Redis 7.0 or later, or Valkey; see Redis or Valkey for what it stores and how much memory to give it.
Redis is required when:
- you run more than one replica, or
[database] urlpoints to an ExotDB server.
[redis]
nodes = ["redis://:${REDIS_PASSWORD}@redis.internal:6379"]Every replica must use the same [redis] key_prefix. For TLS, use rediss:// URLs, with [redis] tls_ca for a private CA and tls_cert/tls_key for a client certificate. With several nodes, Sentinel treats them as Redis Cluster seed nodes. For a Redis replicated with Redis Sentinel, leave nodes empty and list the Sentinels in [redis.sentinel]; Sentinel follows failovers to the new master:
[redis.sentinel]
nodes = ["redis://:${REDIS_SENTINEL_PASSWORD}@s1:26379", "redis://:${REDIS_SENTINEL_PASSWORD}@s2:26379"]
master = "mymaster"
password = "${REDIS_PASSWORD}"See Clustering and [redis].
Before you go live
- Serve every exposed listener over HTTPS. Either set
tlson the listener (see Listener TLS), or put a TLS-terminating reverse proxy in front and settrusted_proxiesso client IPs are correct. Outsidelocalhost, the admin UI's session cookie requires HTTPS. See Listeners & reverse proxy. - Behind a load balancer or proxy, keep
[server] idle_timeout(default620s) above its keep-alive timeout, or it may return 502 errors on reused connections. See Connection timeouts. - Give each replica a unique
HOSTNAME; Sentinel uses it to claim license instance slots. - Run
altcha-sentinel doctorin the container to validate the configuration and check connectivity. See the CLI reference. - Work through the Production checklist.
In this section
- Install with Docker: Run Sentinel v2 as a single Docker container with a mounted configuration file, a data volume, and secrets.
- Install with Docker Compose: Run Sentinel v2 with Docker Compose: one instance on embedded SQLite, or two replicas with PostgreSQL and Valkey.
- Install on Kubernetes: Deploy Sentinel v2 on Kubernetes with plain manifests: a ConfigMap, a Secret, a StatefulSet with health probes, and PostgreSQL and Redis for several replicas.
- Install on AWS ECS: A guide for deploying Sentinel v2 on Amazon ECS will follow; until then, run Sentinel on Docker, Docker Compose, or Kubernetes.
- Install on Azure App Service: Deploy Sentinel v2 on Azure App Service with the Azure CLI: a Linux container, the configuration file on Azure Files, and Azure Database for PostgreSQL.