Configuration
Alga is configured via environment variables. The canonical reference is apps/backend/.env.example — copy it to apps/backend/.env and fill in the values. A YAML config file (CONFIG_PATH) is also supported for non-route settings; environment variables always override the YAML file, and the YAML file overrides built-in defaults.
setup.sh generates .env files with random secrets for local Docker Compose. Use it for a fast start:
./setup.sh && docker compose up -dThe default values below come from Defaults() in apps/backend/config/config.go. Duration values use Go duration syntax (30s, 10m, 12h, 168h). Boolean values accept true/false (and other strconv.ParseBool forms).
Precedence: .env Overrides the Inherited Environment
The backend loads .env files with godotenv.Overload semantics: for every key present in apps/backend/.env (or the repo-root .env), the file value replaces any same-named variable inherited from your shell, container environment, or secret provider. This is the reverse of common dotenv conventions — exporting a variable has no effect while the same key exists in a loaded .env. To let an environment-provided value win (container environment: blocks, systemd units, secret managers), delete or comment out that key in .env.
Full resolution order (lowest to highest): built-in defaults → YAML config file (CONFIG_PATH) → environment variables (with .env overriding inherited environment per above) → System Configuration API for its supported keys.
General
| Variable | Default | Required | Description |
|---|---|---|---|
PORT | 8080 | No | Backend HTTP listen port |
LOG_LEVEL | info | No | Log level: debug, info, warn, error |
LOG_FILE | No | Path to log file output. Empty logs to stdout | |
LOG_FORMAT | text | No | Log output format: text (human-readable) or json (structured) |
ENVIRONMENT | No | Set to production (or prod) to enforce production checks (secure cookies). Crypto config is required in all environments, not only production | |
CONFIG_PATH | ./config/config.yaml | No | Optional YAML config file path for non-route settings |
ALGA_PUBLIC_URL | No | Public HTTPS origin for absolute links, Telnyx/Twilio callbacks, and SAML SP endpoints |
When upgrading from a version that used ALGA_BASE_URL, rename it to ALGA_PUBLIC_URL. YAML configuration must use alga_public_url instead of alga_base_url; the old names are not aliases. If rolling back to an older binary, restore the previous name for that version.
Admin Bootstrap
On first boot with no users in the database, the frontend redirects to /setup where the operator creates the initial admin account (email, password, and full name) via the setup wizard. The setup wizard is only available when no users exist — once an admin exists, it is disabled.
To reset a user's password later, use the CLI: alga user reset-password <email> (see CLI reference).
Session & Cookies
| Variable | Default | Required | Description |
|---|---|---|---|
SESSION_EXPIRY_HOURS | 24 | No | Sliding (idle) session expiry, in hours |
SESSION_MAX_LIFETIME | 12h | No | Absolute max session lifetime, enforced in addition to idle expiry (ASVS V3.2/V3.3) |
SECURE_COOKIES | false | No | Set the Secure flag on cookies. Auto-enabled when ENVIRONMENT=production and HSTS is emitted on HTTPS regardless |
HTTP Server Hardening
All have safe defaults; override only to tune for your deployment.
| Variable | Default | Description |
|---|---|---|
SERVER_READ_HEADER_TIMEOUT | 10s | Max duration reading request headers (neutralizes slowloris) |
SERVER_READ_TIMEOUT | 30s | Max duration reading the full request (headers + body) |
SERVER_WRITE_TIMEOUT | 30s | Max duration writing the response. SSE handlers clear their own write deadline |
SERVER_IDLE_TIMEOUT | 120s | Max idle time for keep-alive connections |
SERVER_MAX_HEADER_BYTES | 1048576 | Max request header size in bytes (1 MiB) |
PostgreSQL
| Variable | Default | Required | Description |
|---|---|---|---|
POSTGRES_DSN | Yes | PostgreSQL connection string (e.g. postgres://user:pass@localhost:5432/alga?sslmode=disable). Production must use sslmode=require or verify-full | |
POSTGRES_AUTO_MIGRATE | false | No | Run goose migrations on startup (enabled in Docker Compose) |
POSTGRES_MAX_OPEN_CONNS | 25 | No | Max open DB connections in the pool — raise for busy setups with many replicas |
POSTGRES_MAX_IDLE_CONNS | 5 | No | Idle connections kept ready in the pool |
POSTGRES_CONN_MAX_IDLE_TIME | 5m | No | How long an idle connection is kept before closing |
POSTGRES_CONN_MAX_LIFETIME | 30m | No | Max lifetime of a connection before it is recycled |
Cryptography
Fail-closed — required in every environment
ENCRYPTION_KEYS and SECRET_PEPPER are required at startup in all environments, not only production. If either is missing or invalid, the server refuses to start (ASVS V2.1/V6.2).
| Variable | Default | Required | Description |
|---|---|---|---|
ENCRYPTION_KEYS | Yes | Comma-separated kid:base64(32B) pairs for AES-256-GCM envelope encryption. The highest kid seals new ciphertexts; lower kids decrypt historical data. Generate keys with openssl rand -base64 32 (e.g. 1:<base64>,2:<base64>) | |
SECRET_PEPPER | Yes | Base64-encoded HMAC pepper (must decode to >= 32 bytes) for password pre-hashing and token hashing. Generate with openssl rand -base64 32 |
setup.sh generates keys
setup.sh appends a generated ENCRYPTION_KEYS value in the 1:<base64> form above, plus SECRET_PEPPER, to apps/backend/.env.
Envelope format
Ciphertext is stored as enc:v<kid>:base64(12B nonce || AES-256-GCM ciphertext+tag) — e.g. enc:v1:…. The kid picks the HMAC pepper for SECRET_PEPPER-derived token hashes (hex(64) with a 12-hex lookup_prefix for indexed prefix scans) and the Argon2id peppered pre-hash: password bytes are HMAC-SHA-256 with SECRET_PEPPER before Argon2id. cfg.Validate() rejects the process unless both values are present and well-formed — fail-closed in every environment, not only production (see Security & Authentication).
Argon2id Tuning
Defaults follow OWASP 2026 (m=64 MiB, t=3, p=2). Tune so a single hash takes ~250–500ms on production hardware. Memory is the dominant cost; combined with MAX_CONCURRENT_PASSWORD_HASHES it bounds API memory at roughly ARGON2_MEMORY_KIB * MAX_CONCURRENT_PASSWORD_HASHES KiB.
| Variable | Default | Description |
|---|---|---|
ARGON2_MEMORY_KIB | 65536 | Memory cost in KiB (64 MiB). Minimum accepted: 8192 |
ARGON2_TIME | 3 | Iterations. Minimum accepted: 1 |
ARGON2_PARALLELISM | 2 | Parallelism factor. Minimum accepted: 1 |
ARGON2_SALT_LEN | 16 | Salt length in bytes. Minimum accepted: 8 |
ARGON2_KEY_LEN | 32 | Derived key length in bytes. Minimum accepted: 16 |
MAX_CONCURRENT_PASSWORD_HASHES | 2 * NumCPU | Max concurrent hash/verify operations (bounds API memory) |
Trusted Proxies
| Variable | Default | Required | Description |
|---|---|---|---|
TRUSTED_PROXIES | No | Comma-separated list of trusted proxy IPs/CIDRs for rate limiting and client-IP extraction |
Slack
| Variable | Default | Required | Description |
|---|---|---|---|
SLACK_BOT_TOKEN | No | Slack bot token (UI-configurable, stored encrypted). When set via env, the UI fields are locked | |
SLACK_DEFAULT_CHANNEL | No | Default Slack channel for unmatched alerts | |
SLACK_DISABLED | false | No | Disable Slack delivery |
SLACK_SIGNING_SECRET | No | Verifies Slack Events API signatures on /webhooks/slack | |
SLACK_CLIENT_ID | No | Slack app Client ID (enables workspace install via OAuth) | |
SLACK_CLIENT_SECRET | No | Slack app Client Secret (enables workspace install via OAuth) | |
SLACK_OAUTH_REDIRECT_URL | No | Override OAuth callback URL (for reverse-proxy setups) |
To install Alga into a whole Slack workspace at once (instead of pasting a single bot token), fill in the three OAuth rows above — see Slack OAuth Setup. When SLACK_BOT_TOKEN is set directly, the Integrations page fields are locked and the env value wins.
Mattermost
| Variable | Default | Required | Description |
|---|---|---|---|
MATTERMOST_SERVER_URL | No | Mattermost server base URL (Alga appends /plugins/com.alga.mattermost-plugin for the plugin API). When set via env, the UI field is locked | |
MATTERMOST_WEBHOOK_SECRET | No | Shared secret with the Mattermost plugin | |
MATTERMOST_TEAM | No | Mattermost team slug for channel resolution (e.g. engineering) | |
MATTERMOST_DEFAULT_CHANNEL | No | Default Mattermost channel for unmatched alerts | |
MATTERMOST_DISABLED | false | No | Disable Mattermost delivery |
RabbitMQ
| Variable | Default | Required | Description |
|---|---|---|---|
RABBITMQ_URI | No | AMQP URI (enables the async pipeline: alert processing, investigations, email, escalation, triage, SLA) |
Valkey / Redis
| Variable | Default | Required | Description |
|---|---|---|---|
VALKEY_ADDR | No | Valkey/Redis address (enables sessions, caching, rate limiting, leader election, presence, SLA, escalation state, on-call cache, idempotency replay) | |
VALKEY_PASSWORD | No | Valkey/Redis password | |
VALKEY_DB | 0 | No | Database number |
Idempotency & Outbox
| Variable | Default | Required | Description |
|---|---|---|---|
IDEMPOTENCY_ENABLED | true | No | Enable Idempotency-Key replay for opted-in retry-safe writes (create incident, ingest alert webhook, notification send, agent state-changing actions). Requires Valkey; no-op when Valkey is not configured |
IDEMPOTENCY_TTL | 24h | No | How long a cached response is replayed for a repeated Idempotency-Key before the key expires |
ALGA_OUTBOX_RETENTION | 168h (7 days) | No | Retention window for published transactional-outbox rows before pruning. Set to 0 to disable pruning |
Automation
| Variable | Default | Required | Description |
|---|---|---|---|
AUTOMATION_WEBHOOK_ALLOWED_HOSTS | Empty | For outbound actions | Comma-separated exact DNS names approved for automation HTTPS requests |
AUTOMATION_WEBHOOK_PRIVATE_HOSTS | Empty | No | Approved names that may resolve to RFC1918 or ULA addresses; unsafe addresses stay blocked |
Hermes / SRE Agent
| Variable | Default | Required | Description |
|---|---|---|---|
HERMES_PLATFORM_URL | No | Hermes platform base URL (stored in the integrations table, encrypted token) | |
HERMES_PLATFORM_TOKEN | No | Hermes platform bearer token (encrypted at rest) |
Agent connections use per-agent tokens
Agent dispatch and SSE connections use bearer tokens created per-agent in the Alga UI (alga_agent_...), not HERMES_PLATFORM_TOKEN. The platform URL/token fields are stored encrypted in the integrations table and surfaced via the integration config API.
Agent SSE
| Variable | Default | Required | Description |
|---|---|---|---|
AGENT_SSE_ALLOWED_ORIGINS | No | Comma-separated Origin allowlist for the agent SSE endpoint. Empty allows all origins | |
AGENT_SSE_ALLOW_QUERY_TOKEN | false | No | Temporary escape hatch: allow the agent token as ?token= on the SSE stream. Keep off — tokens in URLs leak into logs. Use the Authorization header instead |
Webhook & Agent Token Escape Hatches
Tokens normally travel in the Authorization header. These flags re-enable the old ?token= URL fallback for senders that can't set headers. Both are off by default, log a loud warning when on, and will be removed in a future release.
| Variable | Default | Required | Description |
|---|---|---|---|
WEBHOOK_ALLOW_QUERY_TOKEN | false | No | Allow webhook tokens as ?token= on POST /webhooks/alerts |
AGENT_SSE_ALLOW_QUERY_TOKEN | false | No | Allow agent tokens as ?token= on GET /api/v1/agent/events |
Rate Limiting
| Variable | Default | Required | Description |
|---|---|---|---|
RATE_LIMIT_GENERAL_PER_MINUTE | 20 | No | Max requests per minute per IP on public endpoints (login, webhooks, setup). Raise if a busy sender posts more than 20/min from one IP |
RATE_LIMIT_AGENT_PER_MINUTE | 120 | No | Max requests per minute per agent token on agent endpoints |
Alert Correlation
| Variable | Default | Required | Description |
|---|---|---|---|
CORRELATION_WINDOW | 15s | No | Time window during which alerts sharing a correlation key are buffered and merged into one investigation. 0 flushes each alert immediately (no grouping delay) |
CORRELATION_COOLDOWN_TTL | 30m | No | Cooldown after investigation publish (prevents duplicates) |
Investigation
| Variable | Default | Required | Description |
|---|---|---|---|
INVESTIGATION_TIMEOUT | 10m | No | Investigation timeout |
MAX_CONCURRENT_INVESTIGATIONS | 3 | No | Max parallel investigations per agent |
MAX_CONCURRENT_COMMAND | 3 | No | Max concurrent command dispatches |
STATUS_UPDATE_INTERVAL | 15m | No | Default cadence for incident status updates |
INVESTIGATION_CHANNEL | No | Slack or Mattermost channel for investigation threads | |
CRITICAL_SEVERITY_LABELS | No | Comma-separated labels that trigger critical escalation |
Scheduler HA & Presence
| Variable | Default | Required | Description |
|---|---|---|---|
SCHEDULER_LEADER_TTL | 15s | No | Leader lease TTL for scheduler HA. Set to 0 for single-replica |
AGENT_PRESENCE_TTL | 90s | No | Agent SSE presence TTL (renewed via heartbeat/keepalive) |
AGENT_DISCONNECT_GRACE | 45s | No | Grace period before resetting work on agent disconnect |
CANCEL_SET_TTL | 168h (7 days) | No | How long a deleted entity's cancel marker lives in Valkey so workers skip it without hitting Postgres. Must exceed the max RabbitMQ retry/DLQ horizon |
Stale Alert Sweep
| Variable | Default | Required | Description |
|---|---|---|---|
STALE_ALERT_THRESHOLD | 15m | No | Minimum age before a firing alert with no investigation is considered stale. 0 disables |
STALE_ALERT_SWEEP_INTERVAL | 5m | No | How often the scheduler scans for stale alerts |
SLA Sweep
| Variable | Default | Required | Description |
|---|---|---|---|
SLA_SWEEP_INTERVAL | 60s | No | How often the scheduler leader publishes an SLA breach-detection sweep tick. Values ≤ 0 disable publication entirely |
Stuck-Investigation Escalation
| Variable | Default | Required | Description |
|---|---|---|---|
STUCK_INVESTIGATION_ESCALATION_MULTIPLIER | 2 | No | Multiple of INVESTIGATION_TIMEOUT after which an in-progress investigation is "stuck" and pages the ops team. Set to 0 to disable |
STUCK_INVESTIGATION_ESCALATION_TICK_INTERVAL | 30s | No | How often the stuck-investigation escalation worker runs |
OPS_TEAM_NAME | ops-team | No | Team whose schedule is the human-on-call target for stuck-investigation and forced-channel escalations |
Voice Escalation
Alga supports two voice providers for phone-call escalation: Twilio (default) and Telnyx. They are mutually exclusive — only the selected provider is active. Set VOICE_PROVIDER to choose; switching requires a restart. When unset, the provider can be chosen from the Integrations UI (persisted in the DB).
| Variable | Default | Required | Description |
|---|---|---|---|
VOICE_PROVIDER | twilio | No | twilio or telnyx. Unrecognized values normalize to twilio. Setting this locks the UI selector |
Twilio
| Variable | Default | Required | Description |
|---|---|---|---|
TWILIO_ACCOUNT_SID | No | Twilio account SID. When set via env, the UI fields are locked and env takes precedence | |
TWILIO_AUTH_TOKEN | No | Twilio auth token (required for callback validation) | |
TWILIO_FROM_NUMBER | No | Twilio outbound phone number | |
TWILIO_DISABLED | false | No | Disable Twilio entirely |
Telnyx
| Variable | Default | Required | Description |
|---|---|---|---|
TELNYX_API_KEY | No | Telnyx API key. When set via env, the UI fields are locked | |
TELNYX_CONNECTION_ID | No | Telnyx Call Control Application ID | |
TELNYX_FROM_NUMBER | No | Telnyx outbound phone number | |
TELNYX_PUBLIC_KEY | No | Ed25519 public key (base64) from the Telnyx portal, used to verify inbound call-control webhooks at /api/v1/telnyx/callback. Required when VOICE_PROVIDER=telnyx | |
TELNYX_DISABLED | false | No | Disable Telnyx entirely |
TELNYX_TTS_VOICE | No | TTS voice for spoken prompts (e.g. Polly.Brian, Azure.en-CA-ClaraNeural, ElevenLabs.eleven_flash_v2_5.<voice_id>). Defaults to a free Telnyx voice | |
TELNYX_TTS_LANGUAGE | No | TTS language | |
TELNYX_TTS_API_KEY_REF | No | Identifier of a Telnyx integration secret holding the ElevenLabs API key. Required only when TELNYX_TTS_VOICE starts with ElevenLabs. |
SMTP / Email
Required for password reset emails and email notifications. If SMTP_HOST is empty, password reset emails are logged but not delivered.
| Variable | Default | Required | Description |
|---|---|---|---|
SMTP_HOST | No | SMTP relay hostname (enables email notifications + password reset) | |
SMTP_PORT | 587 | No | SMTP port |
SMTP_USER | No | SMTP auth username | |
SMTP_PASSWORD | No | SMTP auth password | |
SMTP_FROM | No | From address for email notifications | |
SMTP_SKIP_TLS_VERIFY | false | No | Skip TLS certificate verification for SMTP. Security risk — logs a loud warning on startup when enabled (ASVS V9.2) |
Agent Memory
pgvector-backed shared agent memory for extracting and searching investigation memories.
| Variable | Default | Required | Description |
|---|---|---|---|
MEMORY_ENABLED | false | No | Enable agent memory |
MEMORY_EMBEDDING_URL | No | OpenAI-compatible embedding API URL | |
MEMORY_EMBEDDING_API_KEY | No | API key for the embedding service | |
MEMORY_EMBEDDING_MODEL | No | Embedding model name — must be 1536-dimension (boot-time check rejects others) | |
MEMORY_LLM_URL | No | OpenAI-compatible LLM API URL for memory extraction | |
MEMORY_LLM_API_KEY | No | API key for the extraction LLM | |
MEMORY_LLM_MODEL | No | LLM model for memory extraction | |
MEMORY_AUTO_EXTRACT | false | No | Auto-extract memories on investigation completion |
MEMORY_MAX_PER_INVESTIGATION | No | Hard cap on memories extracted per investigation; LLM results are truncated to this before embedding (default 10) | |
MEMORY_SIMILARITY_THRESHOLD | No | Min search score (0–1) for results to be returned; applied as a post-filter on the vector and text search paths. 0 returns the raw top-K |
Triage
| Variable | Default | Required | Description |
|---|---|---|---|
TRIAGE_ENABLED | false | No | Enable the triage system |
TRIAGE_LLM_URL | No | LLM API URL for triage decisions | |
TRIAGE_LLM_API_KEY | No | API key for the triage LLM | |
TRIAGE_LLM_MODEL | No | LLM model for triage | |
TRIAGE_MAX_CONCURRENT | 3 | No | Max concurrent triage operations |
TRIAGE_TIMEOUT | 2m | No | Triage operation timeout |
MAX_CONCURRENT_TRIAGE | 5 | No | Max concurrent triage workers |
TRIAGE_CONFIDENCE_THRESHOLD | 0.7 | No | Min confidence for auto-decisions; below this, decisions downgrade to enrich_only |
TRIAGE_AUTO_RESOLVE_ENABLED | false | No | Allow auto_resolve decisions (otherwise downgrades to enrich_only) |
TRIAGE_SUPPRESS_ENABLED | false | No | Allow suppress decisions (otherwise downgrades to enrich_only) |
TRIAGE_CONTEXT_EPISODIC_LIMIT | 3 | No | Max episodic context entries |
TRIAGE_CONTEXT_NOTES_LIMIT | 3 | No | Max knowledge notes for context |
TRIAGE_CONTEXT_MEMORIES_LIMIT | 5 | No | Max agent memories for context |
TRIAGE_AUTO_PROMOTE_CONFIRMED_COUNT | 3 | No | Confirmed results of the same correlation key + decision before new triages for that key skip the LLM (0 disables) |
Google OAuth
Enables "Sign in with Google" on the login page.
| Variable | Default | Required | Description |
|---|---|---|---|
GOOGLE_CLIENT_ID | No | Google OAuth client ID | |
GOOGLE_CLIENT_SECRET | No | Google OAuth client secret | |
GOOGLE_OAUTH_REDIRECT_URL | No | Override callback URL (auto-detected from request headers if not set) | |
GOOGLE_OAUTH_ENABLED | true | No | Toggle Google Sign-In |
Google Meet (War Rooms)
Auto-creates a Google Meet space per incident for war-room coordination. Requires a service-account JSON with the Meet API enabled and domain-wide delegation for scope https://www.googleapis.com/auth/meet.space.admin.
| Variable | Default | Required | Description |
|---|---|---|---|
GOOGLE_MEET_ENABLED | false | No | Enable Google Meet integration |
GOOGLE_MEET_CREDENTIALS_PATH | No | Path to the service-account JSON | |
GOOGLE_MEET_AUTO_CREATE | true | No | Auto-create a Meet space when an incident goes active |
Data Retention
| Variable | Default | Required | Description |
|---|---|---|---|
DATA_RETENTION_DAYS | 90 | No | Days to keep resolved alerts plus related triage results and delivery records. Set to 0 to keep forever. (Audit history uses AUDIT_RETENTION_DAYS below, not this setting) |
AUDIT_RETENTION_DAYS | 365 | No | Days to retain audit logs; pruned by the hourly retention sweeper alongside DATA_RETENTION_DAYS. Set to 0 to keep forever |
Observability (OpenTelemetry)
Tracing is env-gated and off by default. When disabled, a noop tracer provider is installed and tracing has zero runtime cost. Tracing turns on when ALGA_OTEL_ENABLED=true or an OTLP endpoint is configured.
| Variable | Default | Required | Description |
|---|---|---|---|
ALGA_OTEL_ENABLED | false | No | Master switch for OpenTelemetry tracing |
OTEL_EXPORTER_OTLP_ENDPOINT | No | OTLP/HTTP collector endpoint. The standard OTEL_EXPORTER_OTLP_TRACES_ENDPOINT is also honored | |
ALGA_OTEL_SAMPLE_RATIO | 1.0 (when tracing enabled) | No | Fraction (0.0–1.0) of new traces sampled via a ParentBased(TraceIDRatioBased) sampler |
Frontend
The frontend is a Vite app; its variables are prefixed with VITE_ and read at build time.
| Variable | Default | Required | Description |
|---|---|---|---|
VITE_API_BASE_URL | No | API base URL override for the frontend. Leave empty to use the Vite dev proxy |
Features With No Environment Variables
These features are configured entirely through the API/UI, not environment variables:
- Playbooks — managed via
/api/v1/playbooks - Heartbeats — managed via
/api/v1/heartbeats - Status Pages — managed via
/api/v1/status-pages - Credential Providers & Shared Secrets — managed via
/api/v1/credential-providersand/api/v1/shared-secrets - Incident Summaries —
incident_summary_enabled,incident_summary_interval, and per-severityincident_summary_intervalsare managed via the System Configuration API - On-Call Reminders — on-call shift handoff detection runs on the scheduler; reminder behavior is not controlled by environment variables
System Configuration API
Runtime settings can also be managed via the API at PUT /api/v1/system/config. For supported settings this overrides environment variables. See System Configuration API.