# Configuration settings

> Every setting InfraInbox's loader knows about, generated from the config struct, each with its YAML key, environment variable, default and meaning.

Web page: https://infrainbox.app/docs/reference/config-settings/

Generated by `make generate` (`tools/configdocs`) from `internal/platform/config`'s struct
tags and doc comments — don't hand-edit it; CI's drift check fails a branch that edits the config
struct without regenerating this page. For the narrated, task-oriented version with examples, see
[Configuration reference](https://infrainbox.app/docs/self-hosting/configuration.md).

Every default below is `Defaults()`'s literal value, before any environment-specific derivation (a few,
such as `http.listen`'s port, depend on another setting and are explained on the page linked above).
`required` means the server refuses to start without it; `secret` means it also accepts the
`_FILE` variant, which a deployment should prefer.

## General

| Setting | Environment variable | Default | Meaning |
|---|---|---|---|
| `mode` | `INFRAINBOX_MODE` | `self-hosted` | Deployment mode: self-hosted, or cloud (invite-only signup, email verification, quotas, stricter SSRF rules; PRD §35.4). Not the process mode, which is serve.mode. (one of: self-hosted, cloud) |
| `public_url` | `INFRAINBOX_PUBLIC_URL` | `""` | External base URL of the web UI and the /v1 API, as users and phones reach it (https://notify.example.com:8443). (**required**; alias `PUBLIC_URL`) |
| `ingest_url` | `INFRAINBOX_INGEST_URL` | `""` | Base URL that generated source configurations send events to (Cloud: https://api.infrainbox.app). Empty means public_url (PRD §35.4). |
| `data_dir` | `INFRAINBOX_DATA_DIR` | `/var/lib/infrainbox` | Directory for the master key and TLS material; back it up with the database (PRD §35.1). |
| `master_key` | `INFRAINBOX_MASTER_KEY` | `""` | The master key (KEK): 32 bytes in standard base64 (`openssl rand -base64 32`). Prefer INFRAINBOX_MASTER_KEY_FILE to the plain variable. Unset: <data_dir>/master.key, generated on the first start of a fresh database; back it up with the data directory (PRD §31.5). Required in cloud mode, which never generates one (D43). (secret, prefer `_FILE`) |
| `master_key_previous` | `INFRAINBOX_MASTER_KEY_PREVIOUS` | `""` | The master key being rotated away from, same format: set it (prefer INFRAINBOX_MASTER_KEY_PREVIOUS_FILE) with the new key as master_key, restart, then run `infrainbox admin keys rotate`. The server opens secrets under either key and refuses to start without this one while any secret still needs it (PRD §31.5). (secret, prefer `_FILE`) |

## Serve

Serve holds the settings of the serve command's process.

| Setting | Environment variable | Default | Meaning |
|---|---|---|---|
| `serve.mode` | `INFRAINBOX_SERVE_MODE` | `all` | Which components this process runs: all (self-hosted), or api and worker as separate processes (Cloud). Flag: serve --mode. (one of: all, api, worker) |
| `serve.stop_grace` | `INFRAINBOX_SERVE_STOP_GRACE` | `30s` | Grace between SIGTERM and SIGKILL that the platform allows; shutdown finishes 3 s before it (arch 03 §11). Match the Compose stop_grace_period. (at least 5s) |

## Log

Log holds the logging settings: JSON lines on stderr (PRD §55).

| Setting | Environment variable | Default | Meaning |
|---|---|---|---|
| `log.level` | `INFRAINBOX_LOG_LEVEL` | `info` | Lowest level logged: debug, info, warn or error. Event and notification bodies appear only at debug, and never in cloud mode. (one of: debug, info, warn, error) |

## Database

Database holds the PostgreSQL settings.

| Setting | Environment variable | Default | Meaning |
|---|---|---|---|
| `database.url` | `INFRAINBOX_DATABASE_URL` | `""` | PostgreSQL connection URL or DSN. It usually carries the password, so it is a secret: prefer INFRAINBOX_DATABASE_URL_FILE. LISTEN needs a direct connection, not a transaction pooler. (**required**; secret, prefer `_FILE`; alias `DATABASE_URL`) |
| `database.app_max_conns` | `INFRAINBOX_DATABASE_APP_MAX_CONNS` | `20` | Maximum connections of the API pool (ingest and /v1). (at least 1) |
| `database.worker_max_conns` | `INFRAINBOX_DATABASE_WORKER_MAX_CONNS` | `10` | Maximum connections of the worker pool (deliveries and scheduler). (at least 1) |

## HTTP

HTTP holds the main listener's settings.

| Setting | Environment variable | Default | Meaning |
|---|---|---|---|
| `http.listen` | `INFRAINBOX_HTTP_LISTEN` | `""` | Address of the main listener. Empty means :8443 with TLS on and :8080 with tls.mode off. |
| `http.trusted_proxies` | `INFRAINBOX_HTTP_TRUSTED_PROXIES` | `[]` | Proxies whose X-Forwarded-* headers are trusted for the client IP and scheme: IP addresses or CIDR prefixes. Default (D60): none with tls.mode on, which serves clients directly; loopback and private ranges with tls.mode off, which runs behind a reverse proxy. Cloud mode requires an explicit list. |
| `http.trusted_hosts` | `INFRAINBOX_HTTP_TRUSTED_HOSTS` | `[]` | Other hostnames the web UI, sign-in and the /v1 API answer to besides PUBLIC_URL's, e.g. notify.home.arpa,infrainbox.example.com. Any other name gets a 421 (DNS-rebinding protection, D62); localhost and IP addresses always work, and ingest, heartbeats, health and metrics are never checked. Hostnames only: no scheme, port or wildcard. (alias `TRUSTED_HOSTS`) |
| `http.read_header_timeout` | `INFRAINBOX_HTTP_READ_HEADER_TIMEOUT` | `10s` | Longest wait for a request's headers; guards against slow clients. (at least 1s) |
| `http.read_timeout` | `INFRAINBOX_HTTP_READ_TIMEOUT` | `1m` | Longest time to read a whole request, body included. (at least 1s) |
| `http.write_timeout` | `INFRAINBOX_HTTP_WRITE_TIMEOUT` | `1m` | Longest time to write a response. Streaming routes (/v1/stream) lift it per request. (at least 1s) |
| `http.idle_timeout` | `INFRAINBOX_HTTP_IDLE_TIMEOUT` | `2m` | How long an idle keep-alive connection stays open. (at least 1s) |
| `http.max_header_bytes` | `INFRAINBOX_HTTP_MAX_HEADER_BYTES` | `65536` | Largest request header block, in bytes. (at least 4096) |

## TLS

TLS holds the TLS settings (PRD §35.2; policy §37).

| Setting | Environment variable | Default | Meaning |
|---|---|---|---|
| `tls.mode` | `INFRAINBOX_TLS` | `"on"` | on: HTTPS with cert_file/key_file, or else a self-signed certificate generated into data_dir. off: plain HTTP behind a TLS reverse proxy. (one of: on, off) |
| `tls.cert_file` | `INFRAINBOX_TLS_CERT_FILE` | `""` | PEM certificate chain served on the main listener. |
| `tls.key_file` | `INFRAINBOX_TLS_KEY_FILE` | `""` | PEM private key of cert_file. |
| `tls.ca_file` | `INFRAINBOX_TLS_CA_FILE` | `""` | PEM CA certificate of a private-CA chain; its pin goes into the pairing QR code. |
| `tls.pin` | `INFRAINBOX_TLS_PIN` | `[]` | Pin is one or more SPKI SHA-256 pins (the pairing-qr.v2 `sha256/<base64>` form), for a certificate this process never sees: TLS off behind a reverse proxy whose own certificate isn't publicly trusted and whose file tls.ca_file could point at isn't reachable from here either (P5-SEC-02). Compute one with, for example, `openssl x509 -in proxy-cert.pem -pubkey -noout \| openssl pkey -pubin -outform der \| openssl dgst -sha256 -binary \| base64`. |
| `tls.insecure_http` | `INFRAINBOX_INSECURE_HTTP` | `"off"` | private: also serve plain HTTP, on the HTTPS port, to peers in private ranges only (LAN phones, PRD §8.6). off: never. It needs mode: on, and cloud mode refuses it: plain HTTP is never served in Cloud, where the instances' own network is private. (one of: off, private) |

## Metrics

Metrics holds the /metrics settings (PRD §55).

| Setting | Environment variable | Default | Meaning |
|---|---|---|---|
| `metrics.listen` | `INFRAINBOX_METRICS_LISTEN` | `127.0.0.1:9464` | Address of the internal listener that serves /metrics. |
| `metrics.token` | `INFRAINBOX_METRICS_TOKEN` | `""` | Bearer token that also serves /metrics on the main listener instead; empty keeps it on the internal listener only. (secret, prefer `_FILE`) |

## Migrations

Migrations holds the schema-migration settings (PRD §35.3).

| Setting | Environment variable | Default | Meaning |
|---|---|---|---|
| `migrations.auto` | `INFRAINBOX_MIGRATIONS_AUTO` | `true` | Apply pending migrations when serve starts. Cloud sets false and runs `infrainbox migrate up` as a release step; serve then refuses to start while migrations are pending. |

## Retention

Retention holds how long data is kept (PRD §39). Durations take s, m, h or d units ("30d"); 0 keeps the data forever.

| Setting | Environment variable | Default | Meaning |
|---|---|---|---|
| `retention.events` | `INFRAINBOX_RETENTION_EVENTS` | `30d` | Events. The first and last event of every retained incident are kept. |
| `retention.incidents` | `INFRAINBOX_RETENTION_INCIDENTS` | `90d` | Incidents, counted from resolution. Open incidents are never purged. |
| `retention.deliveries` | `INFRAINBOX_RETENTION_DELIVERIES` | `30d` | Delivery rows; they are summarized on the incident. |
| `retention.raw_payloads` | `INFRAINBOX_RETENTION_RAW_PAYLOADS` | `7d` | Raw payloads (D35). |
| `retention.raw_payloads_per_source` | `INFRAINBOX_RETENTION_RAW_PAYLOADS_PER_SOURCE` | `20` | Raw payloads kept per source, besides parse and credential failures. |
| `retention.heartbeat_pings_per_monitor` | `INFRAINBOX_RETENTION_HEARTBEAT_PINGS_PER_MONITOR` | `100` | Heartbeat pings kept per monitor. |
| `retention.heartbeat_aggregates` | `INFRAINBOX_RETENTION_HEARTBEAT_AGGREGATES` | `90d` | Daily heartbeat aggregates. |
| `retention.idempotency_keys` | `INFRAINBOX_RETENTION_IDEMPOTENCY_KEYS` | `1d` | Idempotency keys; at least 24 h (PRD §10). (at least 24h) |
| `retention.audit` | `INFRAINBOX_RETENTION_AUDIT` | `365d` | Audit log entries. |
| `retention.expired_sessions` | `INFRAINBOX_RETENTION_EXPIRED_SESSIONS` | `30d` | Sessions and pairing tokens, counted from expiry. |

## OTel

OTel holds the OpenTelemetry tracing settings (PRD §55, arch 03 §13).

| Setting | Environment variable | Default | Meaning |
|---|---|---|---|
| `otel.traces` | `INFRAINBOX_OTEL_TRACES` | `false` | Export traces over OTLP. Default: on in cloud mode or when endpoint is set, off otherwise. |
| `otel.endpoint` | `INFRAINBOX_OTEL_ENDPOINT` | `""` | OTLP endpoint (https://otel.example.com:4318). (alias `OTEL_EXPORTER_OTLP_ENDPOINT`) |
| `otel.headers` | `INFRAINBOX_OTEL_HEADERS` | `""` | OTLP headers, key=value pairs separated by commas; often an API key. (secret, prefer `_FILE`; alias `OTEL_EXPORTER_OTLP_HEADERS`) |

## Delivery

Delivery holds the delivery workers' settings (PRD §57).

| Setting | Environment variable | Default | Meaning |
|---|---|---|---|
| `delivery.concurrency.telegram` | `INFRAINBOX_DELIVERY_CONCURRENCY_TELEGRAM` | `8` | (at least 1) |
| `delivery.concurrency.slack` | `INFRAINBOX_DELIVERY_CONCURRENCY_SLACK` | `8` | (at least 1) |
| `delivery.concurrency.discord` | `INFRAINBOX_DELIVERY_CONCURRENCY_DISCORD` | `8` | (at least 1) |
| `delivery.concurrency.email` | `INFRAINBOX_DELIVERY_CONCURRENCY_EMAIL` | `4` | (at least 1) |
| `delivery.concurrency.webhook` | `INFRAINBOX_DELIVERY_CONCURRENCY_WEBHOOK` | `16` | (at least 1) |
| `delivery.concurrency.ntfy` | `INFRAINBOX_DELIVERY_CONCURRENCY_NTFY` | `8` | (at least 1) |
| `delivery.concurrency.pushover` | `INFRAINBOX_DELIVERY_CONCURRENCY_PUSHOVER` | `2` | (at least 1) |
| `delivery.concurrency.gotify` | `INFRAINBOX_DELIVERY_CONCURRENCY_GOTIFY` | `8` | (at least 1) |
| `delivery.concurrency.push` | `INFRAINBOX_DELIVERY_CONCURRENCY_PUSH` | `32` | (at least 1) |
| `delivery.concurrency.per_workspace_percent` | `INFRAINBOX_DELIVERY_CONCURRENCY_PER_WORKSPACE_PERCENT` | `25` | PerWorkspacePercent caps one workspace's share of every kind's pool above, as a percentage of that kind's size (rounded up, floored at 1): one workspace's blackholed webhook destinations or paired devices can then hold only their own share of the slots, never every tenant's (PRD §57, P8-BE-10, review H1). 0 disables the cap (every slot shared, the pre-P8-BE-10 behaviour). (at least 0) |

## Push

Push holds the phone push paths (PRD §21.2, §23.3). No path is mandatory: with every one off, the server still delivers to Telegram, email and the other destinations.

| Setting | Environment variable | Default | Meaning |
|---|---|---|---|
| `push.webpush.vapid_key` | `INFRAINBOX_PUSH_WEBPUSH_VAPID_KEY` | `""` | The VAPID private key. Empty or auto: a P-256 key is generated at the first start and stored in the database, encrypted with the master key. Otherwise the raw 32-byte P-256 private key in base64url; prefer INFRAINBOX_PUSH_WEBPUSH_VAPID_KEY_FILE. Cloud mode requires the file. Rotating the key forces every paired device to re-register its push subscription: set a new key, or, with auto, delete the stored one (`DELETE FROM system_state WHERE key = 'push.vapid'`) and restart. (secret, prefer `_FILE`) |
| `push.webpush.subject` | `INFRAINBOX_PUSH_WEBPUSH_SUBJECT` | `""` | Contact for push services about this server's traffic (RFC 8292 `sub`): a mailto: address or an https URL, e.g. mailto:admin@example.com. |
| `push.relay.enabled` | `INFRAINBOX_PUSH_RELAY_ENABLED` | `true` | Advertise the relay in /v1/info and the pairing QR code; the apps register with it themselves. |
| `push.relay.url` | `INFRAINBOX_PUSH_RELAY_URL` | `https://push.infrainbox.app` | The relay's https base URL. |
| `push.unifiedpush.enabled` | `INFRAINBOX_PUSH_UNIFIEDPUSH_ENABLED` | `true` | Accept UnifiedPush endpoints. |
| `push.apns.enabled` | `INFRAINBOX_PUSH_APNS_ENABLED` | `false` | Send to APNs directly. Needs key, key_id and team_id. |
| `push.apns.key` | `INFRAINBOX_PUSH_APNS_KEY` | `""` | The APNs authentication key (.p8, PEM); prefer INFRAINBOX_PUSH_APNS_KEY_FILE. (secret, prefer `_FILE`) |
| `push.apns.key_id` | `INFRAINBOX_PUSH_APNS_KEY_ID` | `""` | The key's 10-character key ID. |
| `push.apns.team_id` | `INFRAINBOX_PUSH_APNS_TEAM_ID` | `""` | The Apple developer team ID. |
| `push.fcm.enabled` | `INFRAINBOX_PUSH_FCM_ENABLED` | `false` | Send to FCM directly. Cloud mode only (D6): FCM needs the app publisher's credentials. |

## Updates

Updates is the opt-in server update check (PRD §37.7, §38.3; P8-BE-E4; research 03 F3, test S54): off by default, it periodically fetches a static JSON feed (the latest version, its security flag, and each minor's end-of-support month) through the outbound SSRF-guarded client and shows a dashboard banner when a newer security release exists. The request carries no instance identifier, no counters and no usage data — nothing beyond the request itself.

| Setting | Environment variable | Default | Meaning |
|---|---|---|---|
| `updates.check` | `INFRAINBOX_UPDATES_CHECK` | `false` | Check turns the periodic fetch on. Opt-in; the default is off. |
| `updates.feed_url` | `INFRAINBOX_UPDATES_FEED_URL` | `https://infrainbox.app/releases.json` | FeedURL is the release feed to fetch. The guarded client resolves and checks it exactly as any other outbound destination. |

## Outbound

Outbound holds the opt-ins of the outbound SSRF policy (PRD §37.2). Webhooks, chat providers, push, SMTP and test sends may always reach public addresses and, self-hosted, RFC 1918 ones. Loopback, link-local, multicast and cloud metadata addresses are never allowed. Cloud mode refuses both opt-ins.

| Setting | Environment variable | Default | Meaning |
|---|---|---|---|
| `outbound.allow_cgnat` | `INFRAINBOX_OUTBOUND_ALLOW_CGNAT` | `false` | Also allow CGNAT addresses (100.64.0.0/10), e.g. a Tailscale tailnet. Self-hosted only. |
| `outbound.allow_ula` | `INFRAINBOX_OUTBOUND_ALLOW_ULA` | `false` | Also allow IPv6 unique local addresses (fc00::/7). Self-hosted only. |

## Auth

Auth holds the sign-in settings (PRD §8).

| Setting | Environment variable | Default | Meaning |
|---|---|---|---|
| `auth.password` | `INFRAINBOX_AUTH_PASSWORD` | `enabled` | Who may sign in with a password (PRD §8.8): everybody, instance admins only, or nobody - the last two for instances that sign in through an identity provider. `infrainbox admin reset-password` always works, so a broken provider never locks the operator out. (one of: enabled, admins_only, disabled) |
| `auth.require_mfa` | `INFRAINBOX_AUTH_REQUIRE_MFA` | `none` | Who must have a second factor (PRD §8.1, §8.2): nobody, workspace owners and instance admins, or everybody. An affected account without one reaches only TOTP enrolment until it has one. InfraInbox Cloud always applies at least owners. (one of: none, owners, all) |
| `auth.passkeys` | `INFRAINBOX_AUTH_PASSKEYS` | `auto` | Who offers passkeys (PRD §8.8): auto enables them only where a browser can run the ceremony - HTTPS on a domain name whose certificate chains to a system root or to tls.ca_file; on takes the operator's word for a setup this process cannot check, such as a TLS reverse proxy; off never offers them. GET /v1/info reports the outcome and its reason, so the setup wizard can say what to change. (one of: auto, on, off) |
| `auth.password_hash.profile` | `INFRAINBOX_AUTH_PASSWORD_HASH_PROFILE` | `default` | Argon2id cost: default (19 MiB, t=2; right for a Raspberry Pi or a 1 GB host) or large (46 MiB, t=1; bigger hosts). Existing hashes move to the new profile at their next successful sign-in. (one of: default, large) |
| `auth.password_hash.memory_budget_mib` | `INFRAINBOX_AUTH_PASSWORD_HASH_MEMORY_BUDGET_MIB` | `128` | Memory, in MiB, that concurrent password hashing may use in total. Sign-ins beyond it wait up to 2 s, then get 429 rate_limited. The default, 128, runs six default-profile hashes at once. (at least 46) |
| `auth.admin.email` | `INFRAINBOX_AUTH_ADMIN_EMAIL` | `""` | Admin seeds the first instance administrator at start (P0-SEC-12). The administrator's email address, which is also the sign-in identifier. Empty: no seeding. |
| `auth.admin.password` | `INFRAINBOX_AUTH_ADMIN_PASSWORD` | `""` | Admin seeds the first instance administrator at start (P0-SEC-12). The password, read only from INFRAINBOX_AUTH_ADMIN_PASSWORD_FILE. There is deliberately no plain variable: an environment variable is readable through `docker inspect`, a process listing and every child process, and it would sit in the shell history and in the Compose file that set it. (secret, prefer `_FILE`; file only) |
| `auth.providers` | `INFRAINBOX_AUTH_PROVIDERS` | `[]` | The sign-in identity providers (PRD §8.8): each one is a "Continue with <name>" button on the sign-in page, and read-only in the dashboard. A YAML list only, each entry a mapping: - id: authentik # the callback is <public_url>/v1/auth/oidc/authentik/callback type: oidc # oidc, or github name: Authentik # the button's label (default: the id) issuer: https://auth.example.com/application/o/infrainbox/ client_id: infrainbox client_secret_file: /run/secrets/oidc # optional for oidc (PKCE), required for github auto_create: allowed_domains # off \| invite \| allowed_domains \| on allowed_email_domains: [example.com] scopes: [groups] # extra scopes; openid, email and profile are always asked for auto_create decides whether a sign-in nobody has used before creates an account: off never, invite only for an address with a pending invite, allowed_domains only for a verified address in allowed_email_domains, on always. Accounts are matched by the provider's subject, never by email. |
| `auth.oidc.issuer` | `INFRAINBOX_OIDC_ISSUER` | `""` | OIDC is one OpenID Connect provider from the environment (INFRAINBOX_OIDC_ISSUER, _CLIENT_ID, _CLIENT_SECRET_FILE, _NAME, _AUTO_CREATE, _ALLOWED_EMAIL_DOMAINS), for installs configured without a file. Its id is oidc; it is set when issuer is. The issuer URL, exactly as the provider's discovery document states it. |
| `auth.oidc.client_id` | `INFRAINBOX_OIDC_CLIENT_ID` | `""` | OIDC is one OpenID Connect provider from the environment (INFRAINBOX_OIDC_ISSUER, _CLIENT_ID, _CLIENT_SECRET_FILE, _NAME, _AUTO_CREATE, _ALLOWED_EMAIL_DOMAINS), for installs configured without a file. Its id is oidc; it is set when issuer is. The client ID registered at the provider. |
| `auth.oidc.client_secret` | `INFRAINBOX_OIDC_CLIENT_SECRET` | `""` | OIDC is one OpenID Connect provider from the environment (INFRAINBOX_OIDC_ISSUER, _CLIENT_ID, _CLIENT_SECRET_FILE, _NAME, _AUTO_CREATE, _ALLOWED_EMAIL_DOMAINS), for installs configured without a file. Its id is oidc; it is set when issuer is. The client secret, read only from INFRAINBOX_OIDC_CLIENT_SECRET_FILE; unset for a public client, which PKCE protects. (secret, prefer `_FILE`; file only) |
| `auth.oidc.name` | `INFRAINBOX_OIDC_NAME` | `""` | OIDC is one OpenID Connect provider from the environment (INFRAINBOX_OIDC_ISSUER, _CLIENT_ID, _CLIENT_SECRET_FILE, _NAME, _AUTO_CREATE, _ALLOWED_EMAIL_DOMAINS), for installs configured without a file. Its id is oidc; it is set when issuer is. The sign-in button's label. Empty: SSO. |
| `auth.oidc.auto_create` | `INFRAINBOX_OIDC_AUTO_CREATE` | `"off"` | OIDC is one OpenID Connect provider from the environment (INFRAINBOX_OIDC_ISSUER, _CLIENT_ID, _CLIENT_SECRET_FILE, _NAME, _AUTO_CREATE, _ALLOWED_EMAIL_DOMAINS), for installs configured without a file. Its id is oidc; it is set when issuer is. Who a first sign-in creates an account for: off, invite, allowed_domains or on (see auth.providers). (one of: off, invite, allowed_domains, on) |
| `auth.oidc.allowed_email_domains` | `INFRAINBOX_OIDC_ALLOWED_EMAIL_DOMAINS` | `[]` | OIDC is one OpenID Connect provider from the environment (INFRAINBOX_OIDC_ISSUER, _CLIENT_ID, _CLIENT_SECRET_FILE, _NAME, _AUTO_CREATE, _ALLOWED_EMAIL_DOMAINS), for installs configured without a file. Its id is oidc; it is set when issuer is. The verified email domains auto_create: allowed_domains admits. |

## SMTP

SMTP is the relay the server sends mail through (PRD §19, P7-INT-01): the account stream (verification, password reset, invites, security notices), and the alert stream with its own sender and credentials. Unset, nothing is mailed: password reset, sign-up and email change are unavailable, and `infrainbox admin reset-password` is the way back in.

| Setting | Environment variable | Default | Meaning |
|---|---|---|---|
| `smtp.host` | `INFRAINBOX_SMTP_HOST` | `""` | The relay's host name. Setting it turns account mail on. |
| `smtp.port` | `INFRAINBOX_SMTP_PORT` | `0` | The relay's port; 0 picks 587 for starttls, 465 for tls, 25 for none. (at least 0) |
| `smtp.username` | `INFRAINBOX_SMTP_USERNAME` | `""` | The relay's user name; empty sends without authentication. |
| `smtp.password` | `INFRAINBOX_SMTP_PASSWORD` | `""` | The relay's password; prefer INFRAINBOX_SMTP_PASSWORD_FILE. (secret, prefer `_FILE`) |
| `smtp.tls` | `INFRAINBOX_SMTP_TLS` | `starttls` | starttls (STARTTLS required), tls (TLS from the first byte, port 465), or none: plain text, for a relay on the same host or network. Cloud mode refuses none. (one of: starttls, tls, none) |
| `smtp.from` | `INFRAINBOX_SMTP_FROM` | `""` | The account stream's sender, e.g. `InfraInbox <no-reply@example.com>`. |
| `smtp.alerts.host` | `INFRAINBOX_SMTP_ALERTS_HOST` | `""` | The alert stream (the email destination): its own relay and sender, so alert volume can never block a sign-up. Unset, self-hosted alert mail shares the account relay, and Cloud sends none. The relay's host name. Setting it gives the stream a relay of its own. |
| `smtp.alerts.port` | `INFRAINBOX_SMTP_ALERTS_PORT` | `0` | The alert stream (the email destination): its own relay and sender, so alert volume can never block a sign-up. Unset, self-hosted alert mail shares the account relay, and Cloud sends none. The relay's port; 0 picks the TLS mode's default, as for smtp.port. (at least 0) |
| `smtp.alerts.username` | `INFRAINBOX_SMTP_ALERTS_USERNAME` | `""` | The alert stream (the email destination): its own relay and sender, so alert volume can never block a sign-up. Unset, self-hosted alert mail shares the account relay, and Cloud sends none. The relay's user name; empty sends without authentication. |
| `smtp.alerts.password` | `INFRAINBOX_SMTP_ALERTS_PASSWORD` | `""` | The alert stream (the email destination): its own relay and sender, so alert volume can never block a sign-up. Unset, self-hosted alert mail shares the account relay, and Cloud sends none. The relay's password; prefer the _FILE variable. (secret, prefer `_FILE`) |
| `smtp.alerts.tls` | `INFRAINBOX_SMTP_ALERTS_TLS` | `starttls` | The alert stream (the email destination): its own relay and sender, so alert volume can never block a sign-up. Unset, self-hosted alert mail shares the account relay, and Cloud sends none. starttls, tls or none, as for smtp.tls. (one of: starttls, tls, none) |
| `smtp.alerts.from` | `INFRAINBOX_SMTP_ALERTS_FROM` | `""` | The alert stream (the email destination): its own relay and sender, so alert volume can never block a sign-up. Unset, self-hosted alert mail shares the account relay, and Cloud sends none. The stream's sender. |

## RateLimit

RateLimit sizes the rate-limit buckets (PRD §58.1-58.2). Limits are per instance; a multi-instance deployment divides them by its instance count. A denied request gets 429 with Retry-After.

| Setting | Environment variable | Default | Meaning |
|---|---|---|---|
| `ratelimit.ingest_key.per_minute` | `INFRAINBOX_RATELIMIT_INGEST_KEY_PER_MINUTE` | `600` | Per source key on /v1/events and /hooks/*. The burst lets a whole cluster report at once: Proxmox never retries, so a 429 loses an alert. Tokens added per minute. (at least 1) |
| `ratelimit.ingest_key.burst` | `INFRAINBOX_RATELIMIT_INGEST_KEY_BURST` | `300` | Per source key on /v1/events and /hooks/*. The burst lets a whole cluster report at once: Proxmox never retries, so a 429 loses an alert. Bucket capacity: the requests allowed at once. (at least 1) |
| `ratelimit.ingest_workspace.per_minute` | `INFRAINBOX_RATELIMIT_INGEST_WORKSPACE_PER_MINUTE` | `3000` | Per workspace, across all its sources. Tokens added per minute. (at least 1) |
| `ratelimit.ingest_workspace.burst` | `INFRAINBOX_RATELIMIT_INGEST_WORKSPACE_BURST` | `1000` | Per workspace, across all its sources. Bucket capacity: the requests allowed at once. (at least 1) |
| `ratelimit.auth_failures.per_minute` | `INFRAINBOX_RATELIMIT_AUTH_FAILURES_PER_MINUTE` | `30` | Per client IP: every rejected credential takes a token; while the bucket is empty, requests carrying a credential get 429. Tokens added per minute. (at least 1) |
| `ratelimit.auth_failures.burst` | `INFRAINBOX_RATELIMIT_AUTH_FAILURES_BURST` | `20` | Per client IP: every rejected credential takes a token; while the bucket is empty, requests carrying a credential get 429. Bucket capacity: the requests allowed at once. (at least 1) |
| `ratelimit.management.per_minute` | `INFRAINBOX_RATELIMIT_MANAGEMENT_PER_MINUTE` | `1200` | Per user on the /v1 management API. Tokens added per minute. (at least 1) |
| `ratelimit.management.burst` | `INFRAINBOX_RATELIMIT_MANAGEMENT_BURST` | `200` | Per user on the /v1 management API. Bucket capacity: the requests allowed at once. (at least 1) |
| `ratelimit.public.per_minute` | `INFRAINBOX_RATELIMIT_PUBLIC_PER_MINUTE` | `120` | Per client IP on routes without a credential (/v1/info, sign-in). Tokens added per minute. (at least 1) |
| `ratelimit.public.burst` | `INFRAINBOX_RATELIMIT_PUBLIC_BURST` | `60` | Per client IP on routes without a credential (/v1/info, sign-in). Bucket capacity: the requests allowed at once. (at least 1) |
| `ratelimit.destination_test.per_minute` | `INFRAINBOX_RATELIMIT_DESTINATION_TEST_PER_MINUTE` | `6` | Test sends (POST /v1/destinations/{id}/test) per destination, and per workspace across its destinations: each one is a real provider message. Tokens added per minute. (at least 1) |
| `ratelimit.destination_test.burst` | `INFRAINBOX_RATELIMIT_DESTINATION_TEST_BURST` | `3` | Test sends (POST /v1/destinations/{id}/test) per destination, and per workspace across its destinations: each one is a real provider message. Bucket capacity: the requests allowed at once. (at least 1) |
| `ratelimit.destination_test_workspace.per_minute` | `INFRAINBOX_RATELIMIT_DESTINATION_TEST_WORKSPACE_PER_MINUTE` | `30` | Tokens added per minute. (at least 1) |
| `ratelimit.destination_test_workspace.burst` | `INFRAINBOX_RATELIMIT_DESTINATION_TEST_WORKSPACE_BURST` | `10` | Bucket capacity: the requests allowed at once. (at least 1) |
| `ratelimit.telegram_discover.per_minute` | `INFRAINBOX_RATELIMIT_TELEGRAM_DISCOVER_PER_MINUTE` | `30` | Telegram setup probes per browser session: the dashboard polls one for up to 10 minutes while the user messages the bot. Tokens added per minute. (at least 1) |
| `ratelimit.telegram_discover.burst` | `INFRAINBOX_RATELIMIT_TELEGRAM_DISCOVER_BURST` | `10` | Telegram setup probes per browser session: the dashboard polls one for up to 10 minutes while the user messages the bot. Bucket capacity: the requests allowed at once. (at least 1) |
| `ratelimit.source_test.per_minute` | `INFRAINBOX_RATELIMIT_SOURCE_TEST_PER_MINUTE` | `6` | Test events (POST /v1/sources/{id}/test) per source: each queues one real notice per enabled destination (PRD §11, §58.1). Tokens added per minute. (at least 1) |
| `ratelimit.source_test.burst` | `INFRAINBOX_RATELIMIT_SOURCE_TEST_BURST` | `3` | Test events (POST /v1/sources/{id}/test) per source: each queues one real notice per enabled destination (PRD §11, §58.1). Bucket capacity: the requests allowed at once. (at least 1) |
| `ratelimit.heartbeat_monitor.per_minute` | `INFRAINBOX_RATELIMIT_HEARTBEAT_MONITOR_PER_MINUTE` | `60` | Heartbeat pings per monitor (PRD §58.3): a cron pings once a minute, so anything faster is a loop or a leaked URL. Tokens added per minute. (at least 1) |
| `ratelimit.heartbeat_monitor.burst` | `INFRAINBOX_RATELIMIT_HEARTBEAT_MONITOR_BURST` | `10` | Heartbeat pings per monitor (PRD §58.3): a cron pings once a minute, so anything faster is a loop or a leaked URL. Bucket capacity: the requests allowed at once. (at least 1) |
| `ratelimit.watcher_check_in.per_minute` | `INFRAINBOX_RATELIMIT_WATCHER_CHECK_IN_PER_MINUTE` | `6` | Watcher check-ins per source and host (D119): a watcher checks in every 5 minutes and at each start, so anything faster is a restart loop. Tokens added per minute. (at least 1) |
| `ratelimit.watcher_check_in.burst` | `INFRAINBOX_RATELIMIT_WATCHER_CHECK_IN_BURST` | `5` | Watcher check-ins per source and host (D119): a watcher checks in every 5 minutes and at each start, so anything faster is a restart loop. Bucket capacity: the requests allowed at once. (at least 1) |
| `ratelimit.auth.login.per_minute` | `INFRAINBOX_RATELIMIT_AUTH_LOGIN_PER_MINUTE` | `30` | The authentication routes, each per client IP, on top of the exponential backoff per IP and per account (PRD §58.2). POST /v1/auth/login. Tokens added per minute. (at least 1) |
| `ratelimit.auth.login.burst` | `INFRAINBOX_RATELIMIT_AUTH_LOGIN_BURST` | `15` | The authentication routes, each per client IP, on top of the exponential backoff per IP and per account (PRD §58.2). POST /v1/auth/login. Bucket capacity: the requests allowed at once. (at least 1) |
| `ratelimit.auth.totp.per_minute` | `INFRAINBOX_RATELIMIT_AUTH_TOTP_PER_MINUTE` | `30` | The authentication routes, each per client IP, on top of the exponential backoff per IP and per account (PRD §58.2). TOTP verification (P0-SEC-14). Tokens added per minute. (at least 1) |
| `ratelimit.auth.totp.burst` | `INFRAINBOX_RATELIMIT_AUTH_TOTP_BURST` | `15` | The authentication routes, each per client IP, on top of the exponential backoff per IP and per account (PRD §58.2). TOTP verification (P0-SEC-14). Bucket capacity: the requests allowed at once. (at least 1) |
| `ratelimit.auth.reauth.per_minute` | `INFRAINBOX_RATELIMIT_AUTH_REAUTH_PER_MINUTE` | `30` | The authentication routes, each per client IP, on top of the exponential backoff per IP and per account (PRD §58.2). Step-up re-authentication (P0-SEC-13). Tokens added per minute. (at least 1) |
| `ratelimit.auth.reauth.burst` | `INFRAINBOX_RATELIMIT_AUTH_REAUTH_BURST` | `15` | The authentication routes, each per client IP, on top of the exponential backoff per IP and per account (PRD §58.2). Step-up re-authentication (P0-SEC-13). Bucket capacity: the requests allowed at once. (at least 1) |
| `ratelimit.auth.passkey.per_minute` | `INFRAINBOX_RATELIMIT_AUTH_PASSKEY_PER_MINUTE` | `60` | The authentication routes, each per client IP, on top of the exponential backoff per IP and per account (PRD §58.2). Passkey registration and assertion (P2-SEC-02). Tokens added per minute. (at least 1) |
| `ratelimit.auth.passkey.burst` | `INFRAINBOX_RATELIMIT_AUTH_PASSKEY_BURST` | `20` | The authentication routes, each per client IP, on top of the exponential backoff per IP and per account (PRD §58.2). Passkey registration and assertion (P2-SEC-02). Bucket capacity: the requests allowed at once. (at least 1) |
| `ratelimit.auth.link.per_minute` | `INFRAINBOX_RATELIMIT_AUTH_LINK_PER_MINUTE` | `30` | The authentication routes, each per client IP, on top of the exponential backoff per IP and per account (PRD §58.2). Linking an identity provider to an account (P2-SEC-05). Tokens added per minute. (at least 1) |
| `ratelimit.auth.link.burst` | `INFRAINBOX_RATELIMIT_AUTH_LINK_BURST` | `10` | The authentication routes, each per client IP, on top of the exponential backoff per IP and per account (PRD §58.2). Linking an identity provider to an account (P2-SEC-05). Bucket capacity: the requests allowed at once. (at least 1) |
| `ratelimit.auth.setup.per_minute` | `INFRAINBOX_RATELIMIT_AUTH_SETUP_PER_MINUTE` | `20` | The authentication routes, each per client IP, on top of the exponential backoff per IP and per account (PRD §58.2). First-run setup (P0-SEC-11). Tokens added per minute. (at least 1) |
| `ratelimit.auth.setup.burst` | `INFRAINBOX_RATELIMIT_AUTH_SETUP_BURST` | `10` | The authentication routes, each per client IP, on top of the exponential backoff per IP and per account (PRD §58.2). First-run setup (P0-SEC-11). Bucket capacity: the requests allowed at once. (at least 1) |
| `ratelimit.auth.signup.per_minute` | `INFRAINBOX_RATELIMIT_AUTH_SIGNUP_PER_MINUTE` | `10` | The authentication routes, each per client IP, on top of the exponential backoff per IP and per account (PRD §58.2). Cloud sign-up and the links that confirm an address (P7-SEC-01, P7-SEC-03): the credential-retry brake on a wrong or spent code or token. Tokens added per minute. (at least 1) |
| `ratelimit.auth.signup.burst` | `INFRAINBOX_RATELIMIT_AUTH_SIGNUP_BURST` | `10` | The authentication routes, each per client IP, on top of the exponential backoff per IP and per account (PRD §58.2). Cloud sign-up and the links that confirm an address (P7-SEC-01, P7-SEC-03): the credential-retry brake on a wrong or spent code or token. Bucket capacity: the requests allowed at once. (at least 1) |
| `ratelimit.auth.signup_create.per_minute` | `INFRAINBOX_RATELIMIT_AUTH_SIGNUP_CREATE_PER_MINUTE` | `1` | The authentication routes, each per client IP, on top of the exponential backoff per IP and per account (PRD §58.2). SignupCreate caps how many accounts one client IP may open per POST /v1/auth/signup, separately from Signup's retry brake: Cloud sign-up needs no beta code any more (D153, P8-BE-13), so this is the only brake left on account-creation volume. The default is a small burst, then a trickle. Tokens added per minute. (at least 1) |
| `ratelimit.auth.signup_create.burst` | `INFRAINBOX_RATELIMIT_AUTH_SIGNUP_CREATE_BURST` | `3` | The authentication routes, each per client IP, on top of the exponential backoff per IP and per account (PRD §58.2). SignupCreate caps how many accounts one client IP may open per POST /v1/auth/signup, separately from Signup's retry brake: Cloud sign-up needs no beta code any more (D153, P8-BE-13), so this is the only brake left on account-creation volume. The default is a small burst, then a trickle. Bucket capacity: the requests allowed at once. (at least 1) |
| `ratelimit.auth.reset.per_minute` | `INFRAINBOX_RATELIMIT_AUTH_RESET_PER_MINUTE` | `10` | The authentication routes, each per client IP, on top of the exponential backoff per IP and per account (PRD §58.2). Password reset: asking for a link and using it (P7-SEC-02). Tokens added per minute. (at least 1) |
| `ratelimit.auth.reset.burst` | `INFRAINBOX_RATELIMIT_AUTH_RESET_BURST` | `10` | The authentication routes, each per client IP, on top of the exponential backoff per IP and per account (PRD §58.2). Password reset: asking for a link and using it (P7-SEC-02). Bucket capacity: the requests allowed at once. (at least 1) |
| `ratelimit.auth.mail.per_minute` | `INFRAINBOX_RATELIMIT_AUTH_MAIL_PER_MINUTE` | `1` | The authentication routes, each per client IP, on top of the exponential backoff per IP and per account (PRD §58.2). Account mail per address or account: reset links and re-sent verifications, so nobody can flood someone else's inbox. Tokens added per minute. (at least 1) |
| `ratelimit.auth.mail.burst` | `INFRAINBOX_RATELIMIT_AUTH_MAIL_BURST` | `3` | The authentication routes, each per client IP, on top of the exponential backoff per IP and per account (PRD §58.2). Account mail per address or account: reset links and re-sent verifications, so nobody can flood someone else's inbox. Bucket capacity: the requests allowed at once. (at least 1) |
| `ratelimit.invite.workspace.per_minute` | `INFRAINBOX_RATELIMIT_INVITE_WORKSPACE_PER_MINUTE` | `1` | Workspace invitation mail (P8-BE-12, review H3): an owner's POST /v1/workspaces/{id}/invites is unthrottled mail otherwise, which can relay thousands of messages through the account stream and get the sending domain suspended. Per workspace, across every address it invites. Tokens added per minute. (at least 1) |
| `ratelimit.invite.workspace.burst` | `INFRAINBOX_RATELIMIT_INVITE_WORKSPACE_BURST` | `20` | Workspace invitation mail (P8-BE-12, review H3): an owner's POST /v1/workspaces/{id}/invites is unthrottled mail otherwise, which can relay thousands of messages through the account stream and get the sending domain suspended. Per workspace, across every address it invites. Bucket capacity: the requests allowed at once. (at least 1) |
| `ratelimit.invite.account.per_minute` | `INFRAINBOX_RATELIMIT_INVITE_ACCOUNT_PER_MINUTE` | `1` | Workspace invitation mail (P8-BE-12, review H3): an owner's POST /v1/workspaces/{id}/invites is unthrottled mail otherwise, which can relay thousands of messages through the account stream and get the sending domain suspended. Per inviting account, across every workspace it owns. Tokens added per minute. (at least 1) |
| `ratelimit.invite.account.burst` | `INFRAINBOX_RATELIMIT_INVITE_ACCOUNT_BURST` | `20` | Workspace invitation mail (P8-BE-12, review H3): an owner's POST /v1/workspaces/{id}/invites is unthrottled mail otherwise, which can relay thousands of messages through the account stream and get the sending domain suspended. Per inviting account, across every workspace it owns. Bucket capacity: the requests allowed at once. (at least 1) |
| `ratelimit.invite.recipient.per_minute` | `INFRAINBOX_RATELIMIT_INVITE_RECIPIENT_PER_MINUTE` | `1` | Workspace invitation mail (P8-BE-12, review H3): an owner's POST /v1/workspaces/{id}/invites is unthrottled mail otherwise, which can relay thousands of messages through the account stream and get the sending domain suspended. Per (workspace, recipient): a resend to the same address is still allowed, but not in a burst. Tokens added per minute. (at least 1) |
| `ratelimit.invite.recipient.burst` | `INFRAINBOX_RATELIMIT_INVITE_RECIPIENT_BURST` | `3` | Workspace invitation mail (P8-BE-12, review H3): an owner's POST /v1/workspaces/{id}/invites is unthrottled mail otherwise, which can relay thousands of messages through the account stream and get the sending domain suspended. Per (workspace, recipient): a resend to the same address is still allowed, but not in a burst. Bucket capacity: the requests allowed at once. (at least 1) |

## Quotas

Quotas are the per-workspace limits (PRD §58.1): the defaults that `infrainbox admin workspaces limits` overrides for one workspace. 0 means no limit, the self-hosted default; cloud mode takes its own when unset (CloudQuotas).

| Setting | Environment variable | Default | Meaning |
|---|---|---|---|
| `quotas.events_per_day` | `INFRAINBOX_QUOTAS_EVENTS_PER_DAY` | `0` | Events a workspace may ingest per UTC day. Past it, ingest answers 429 with Retry-After until midnight UTC. (at least 0) |
| `quotas.deliveries_per_day` | `INFRAINBOX_QUOTAS_DELIVERIES_PER_DAY` | `0` | Notifications a workspace may have sent per UTC day, in total and to any one destination (PRD §58.4, P7-BE-04). A notice over either cap is recorded SKIPPED `quota` rather than sent; re-notify and fallback sends count too. Cloud must not become a flood relay, so these are anti-abuse caps, not a plan. (at least 0) |
| `quotas.deliveries_per_destination_per_day` | `INFRAINBOX_QUOTAS_DELIVERIES_PER_DESTINATION_PER_DAY` | `0` | (at least 0) |
| `quotas.new_workspace_deliveries_per_day` | `INFRAINBOX_QUOTAS_NEW_WORKSPACE_DELIVERIES_PER_DAY` | `0` | NewWorkspaceDeliveriesPerDay is the lower daily total a workspace takes for its first tenancy.NewWorkspaceDays (PRD §58.4, "lower for new accounts"). A per-workspace override set by `infrainbox admin workspaces limits` wins over it. (at least 0) |
| `quotas.sources` | `INFRAINBOX_QUOTAS_SOURCES` | `0` | Sources, heartbeat checks, destinations (not counting the built-in push one) and members a workspace may have. Creating one more answers 409 quota_exceeded. (at least 0) |
| `quotas.monitors` | `INFRAINBOX_QUOTAS_MONITORS` | `0` | (at least 0) |
| `quotas.destinations` | `INFRAINBOX_QUOTAS_DESTINATIONS` | `0` | (at least 0) |
| `quotas.members` | `INFRAINBOX_QUOTAS_MEMBERS` | `0` | (at least 0) |
| `quotas.workspaces` | `INFRAINBOX_QUOTAS_WORKSPACES` | `0` | Workspaces one account may own. Creating one more answers 409 quota_exceeded. It is per account, not per workspace: nothing here limits how many workspaces somebody is invited into. (at least 0) |

## Cloud

Cloud holds controls that apply to the whole instance, not to one workspace's quota (D153, P8-BE-13).

| Setting | Environment variable | Default | Meaning |
|---|---|---|---|
| `cloud.max_workspaces` | `INFRAINBOX_CLOUD_MAX_WORKSPACES` | `0` | MaxWorkspaces is how many workspaces this Cloud instance holds in total, across every account; 0 means unlimited, the self-hosted default. Past it, sign-up still creates the account, but a new workspace (create, an invite accepted as owner, or a promotion to owner) answers 409 "beta_full" until the product owner raises it (D116). Self-hosted is unaffected: it has no instance-wide ceiling. (at least 0) |

## Legal

Legal holds the published legal document versions Cloud sign-up records acceptance against (D154, P8-SEC-20).

| Setting | Environment variable | Default | Meaning |
|---|---|---|---|
| `legal.terms_version` | `INFRAINBOX_LEGAL_TERMS_VERSION` | `""` | TermsVersion is the Terms of Service version Cloud sign-up's required checkbox accepts; it is stored on the account with the time, so a later change to the Terms is provable against what was actually agreed to. Empty turns Cloud sign-up and the invite-signup checkbox off (404), the same as an unset mailer: the server never records an acceptance it cannot name a version for. Unused self-hosted, which has no Terms checkbox at all. |

## Dev

Dev holds development and test settings only: they point the transports at tools/fakeproviders (make dev, the E2E stack). Never set them in production: the transports would send provider credentials to that URL. Loading warns whenever one is set, and refuses them all in cloud mode.

| Setting | Environment variable | Default | Meaning |
|---|---|---|---|
| `dev.telegram_api_url` | `INFRAINBOX_DEV_TELEGRAM_API_URL` | `""` | Telegram Bot API base URL instead of https://api.telegram.org. |
| `dev.apns_url` | `INFRAINBOX_DEV_APNS_URL` | `""` | APNs base URL instead of Apple's. |
| `dev.fcm_url` | `INFRAINBOX_DEV_FCM_URL` | `""` | FCM base URL instead of Google's. |
| `dev.relay_url` | `INFRAINBOX_DEV_RELAY_URL` | `""` | Push relay base URL instead of InfraInbox's. |
| `dev.github_url` | `INFRAINBOX_DEV_GITHUB_URL` | `""` | GitHub base URL for GitHub sign-in instead of github.com and api.github.com: <base>/login/oauth/authorize, <base>/login/oauth/access_token and <base>/user (tools/fakeproviders' /github). |
