Rolter Environment Variables and Configuration Reference

Environment variables override their corresponding rolter.toml values, and CLI flags override both. Use environment variables for secrets and for anything that changes between deployments — such as ports, database URLs, and provider API keys — so you can keep a single rolter.toml across environments without embedding sensitive values in it.

--help lists the variable behind each flag as [env: NAME] but never prints the value of a secret or a URL that can carry a password: the admin and internal tokens, and the database, Redis, ClickHouse, snapshot, admin and gateway URLs. It is safe to run in an environment that has them set, and to paste into an issue.

Gateway variables#

These variables control the gateway process (rolter-gateway).

Control plane variables#

These variables control the control-plane process (rolter-control), which manages the dashboard, management API, and config propagation.

Sizing the connection pool#

One pool serves everything the control plane does: /internal/snapshot — which every gateway in your fleet polls — plus the whole dashboard CRUD surface, SCIM, SSO, MCP, and the RBAC guard’s per-request membership lookups. Left too small, that budget silently becomes an acquire-timeout queue.

Size ROLTER_DB_MAX_CONNECTIONS against your database’s max_connections, not against gateway count:

ROLTER_DB_MAX_CONNECTIONS × (control replicas)  <  PostgreSQL max_connections − headroom

Leave headroom for migrations, backups, and any other client of the same database. Gateway count is a weak input here — snapshot polls are short and answer 304 Not Modified most of the time, so a large fleet does not need a proportionally large pool.

Keep ROLTER_DB_ACQUIRE_TIMEOUT_SECS bounded. It is what turns pool exhaustion into a fast, attributable error instead of an opaque stall that looks like a database outage.

Bounding writes#

Nothing waits forever on the control plane’s database. ROLTER_DB_LOCK_TIMEOUT_SECS (default 10) and ROLTER_DB_STATEMENT_TIMEOUT_SECS (default 30) are set on every pooled connection, so a write that sits behind another transaction’s row lock, or a statement that runs away, ends with a 504 in the usual error envelope and the code store_timeout. ROLTER_REQUEST_TIMEOUT_SECS (default 60) is the outer bound for everything else a request can wait on; it answers 504 with the code request_timeout. The dashboard learns this bound from the page the control plane serves and gives up on a call 5 seconds after it, so a connection that never answers at all ends with the same message instead of a spinner that never stops. Keep the three in that order, lock below statement below request, so the database answers first and names the cause. Schema migrations run on a connection without the two database bounds, since an index build can legitimately outlast them.

Throttling failed sign-ins#

POST /api/v1/auth/login is an unauthenticated endpoint that runs an argon2id verification for every request. That cost is what makes password guessing expensive — and it is also what makes an unthrottled login endpoint a cheap way to saturate the control plane’s CPU. Rolter therefore counts rejected sign-ins and refuses further ones before any password work happens.

Two counters run independently:

• Per account. ROLTER_LOGIN_MAX_FAILURES rejected attempts inside ROLTER_LOGIN_FAILURE_WINDOW_SECS lock the account for ROLTER_LOGIN_LOCK_SECS. Each further failure doubles the lock, up to ROLTER_LOGIN_MAX_LOCK_SECS.
• Per client address. ROLTER_LOGIN_IP_MAX_FAILURES covers spraying one guess across many accounts, which a per-account counter never catches. The budget is higher because one office egress address is a whole floor of legitimate typos.

Before the lock engages, each rejected attempt is answered a little more slowly than the last, up to ROLTER_LOGIN_MAX_DELAY_MS. A locked attempt is answered 429 with a Retry-After header, so a client waits rather than polling.

Every counter is keyed on the submitted address, never on an account that was found, so throttling reveals nothing about which addresses are registered. Failed attempts, engaged locks and sign-ins that follow one are written to the audit log, and rolter_control_login_attempts counts them by outcome so a credential-stuffing run is visible on your dashboards.

Where the counters live. With ROLTER_REDIS_URL set, they live in Redis and every control-plane replica counts against the same budget. Without it they are process-local, which is correct for a single-node deployment: with N replicas and no Redis, each replica holds its own budget, so an attacker effectively gets N times the allowance. The control plane logs which mode it is in at startup.

openssl rand -hex 32

Update check#

The control plane asks https://api.github.com/repos/rolter-ai/rolter/releases/latest once at boot and every six hours whether a newer stable release exists, and serves the answer from GET /api/v1/version so the dashboard footer can show a small v0.2.0 available hint. The rolter CLI runs the same check beside whatever command you start, caches the answer in ~/.cache/rolter/update-check.json for 24 hours, and prints one line to stderr:

rolter 0.1.0 is installed; 0.2.0 is available: https://github.com/rolter-ai/rolter/releases/latest

What the check does and does not do:

• One request, a 5-second timeout, carrying nothing but a User-Agent: rolter/<version> header. No installation id, no configuration, no credentials.
• It never blocks a command, never changes an exit status, and never logs above debug when it fails. Offline, rate-limited and malformed answers all look the same: no hint, no notice.
• The CLI remembers a failed attempt too: a host that cannot reach api.github.com tries once a day, not on every command, and keeps showing the last release it learned of.
• Pre-release tags are never advertised. A pre-release build (0.2.0-rc.1) is told about the stable release it precedes; a build newer than the latest release stays quiet.
• rolter easy-up supervises both planes in one process and prints the notice once.

ROLTER_UPDATE_CHECK=false (also 0, no, off) turns it off for both the control plane and the CLI. Set it in an air-gapped deployment, or in any script that must make no outbound call at all; the footer then shows the running version alone and /api/v1/version reports "enabled": false.

Shared variables#

These variables apply to both the gateway and the control plane.

Provider key variables#

Provider credentials are not hard-coded variable names — you choose the name and reference it in rolter.toml. Any variable name you set in a provider’s api_key_env field becomes a provider key variable for that deployment.

A variable that holds a deployment secret (ROLTER_KEK, ROLTER_DATABASE_URL, PGPASSWORD, any other ROLTER_ name except ROLTER_GUARDRAIL_TOKEN) cannot be a provider key. The dashboard refuses it with a 400. A gateway that meets such a name in a snapshot serves that provider without a credential and lists the row on /config/problems; a file config that names one fails validation, and rolter-seed --import stops before it writes anything. The same names are not sent as a guardrail webhook or plugin credential either.

[[providers]]name = "openai"kind = "openai"api_base = "https://api.openai.com"api_key_env = "OPENAI_API_KEY"   # Rolter reads os.env["OPENAI_API_KEY"][[providers]]name = "anthropic"kind = "anthropic"api_base = "https://api.anthropic.com"api_key_env = "ANTHROPIC_API_KEY"

Common provider key variables in use: