Skip to content
Alcarta

Configuration reference

Run gw-server config check against the exact environment before rollout. Alcarta has additional bounded tuning keys; this page focuses on settings an operator normally changes.

Setting Purpose
GW_ENVIRONMENT Runtime safety profile, such as development or production
GW_BASE_URL Public HTTPS origin, JWT issuer, and link base
GW_BIND_ADDR Application listener
GW_METRICS_BIND_ADDR Private metrics listener
GW_DATABASE_URL PostgreSQL connection string
GW_REDIS_URL Redis connection string
GW_EVENT_BUS Coordination backend; use Redis for multiple replicas
GW_EXPECT_HA Refuse unsafe process-local coordination in an HA deployment
GW_MIGRATE_ON_BOOT Migration behavior during process startup
GW_SWEEPER_ENABLED Run expiry and cleanup workers in this process
GW_EXECUTOR_ENABLED Run approval execution workers in this process
GW_OUTBOX_ENABLED Run webhook delivery workers in this process
GW_CONFIG_FILE Optional TOML configuration path

Key files

Section titled “Key files”
Setting Purpose
GW_JWT_ACTIVE_KEY_PATH Active Ed25519 signing key
GW_JWT_ACTIVE_KID Identifier placed in new JWT headers
GW_MESSAGE_HANDLE_KEY_PATH Opaque message-handle root key
GW_SESSION_SECRET_PATH Browser-session root secret
GW_KEK_ACTIVE_ID Active credential-wrapping key version
GW_KEK_ACTIVE_PATH Active credential-wrapping key file

Keep the matching key slot/path configuration for previous keys during rotation. Key material is file-only.

Mail, waits, and payload limits

Section titled “Mail, waits, and payload limits”
Setting Default Purpose
GW_MONITOR_INBOX_MAX_TIMEOUT_SECONDS 300 Maximum inbox wait
GW_MONITOR_APPROVAL_MAX_TIMEOUT_SECONDS 14400 Maximum approval wait
GW_LONGPOLL_FALLBACK_POLL_SECONDS 5 Poll fallback cadence
GW_MAX_BODY_BYTES 1 MiB Normal JSON request limit
GW_MAX_UPLOAD_BYTES 36 MiB Draft requests carrying base64 attachments
GW_MAX_MESSAGE_BYTES 25 MiB Decoded message-size limit
GW_DRAFT_MAX_ATTACHMENTS 10 Attachment-count limit
GW_SEND_MAX_RECIPIENTS 50 Total To, Cc, and Bcc recipients
GW_SEND_MAX_DOMAINS 25 Distinct recipient domains

Telemetry and lifecycle

Section titled “Telemetry and lifecycle”
Setting Purpose
GW_LOG_LEVEL Runtime log filter
GW_OTLP_ENDPOINT Enables OpenTelemetry export when set
GW_OTLP_PROTOCOL grpc or http/protobuf
GW_TRACE_SAMPLE_RATIO Normal trace sampling ratio
GW_SHUTDOWN_GRACE_SECONDS Drain budget for in-flight work
GW_EXECUTOR_WORKERS Approval executor concurrency
GW_OUTBOX_WORKERS Webhook delivery concurrency

Compose uses EMCP_* deployment variables to render canonical GW_* settings into its containers. Consult .env.prod.example beside the Compose file for that mapping.