Environment Variables
Every chatto.toml setting can be overridden with an environment variable. The naming pattern is CHATTO_{SECTION}_{KEY} in uppercase.
General
Section titled “General”CHATTO_LOG_LEVEL Log level. Values: debug, info, warn, error.
CHATTO_LOG_FORMAT Log output format. Values: auto, text, json, logfmt. auto uses text when Chatto is attached to a terminal and JSON otherwise. Use json for Loki/Grafana ingestion so each log line includes a structured level field.
Web Server
Section titled “Web Server”CHATTO_WEBSERVER_URL Public URL of the server, used for absolute links and OAuth redirects.
CHATTO_WEBSERVER_PORT Port to listen on.
CHATTO_WEBSERVER_COOKIE_SIGNING_SECRET 256-bit hex secret for signing session cookies. Generate with openssl rand -hex 32.
CHATTO_WEBSERVER_COOKIE_ENCRYPTION_SECRET Optional hex secret for encrypting session cookies after signing. Must decode to 16, 24, or 32 bytes. Generate an AES-256 key with openssl rand -hex 32.
CHATTO_WEBSERVER_WEBSOCKET_COMPRESSION Enable WebSocket compression.
CHATTO_WEBSERVER_REQUEST_LOGGING Log HTTP requests.
CHATTO_WEBSERVER_ALLOWED_ORIGINS Comma-separated list of origins allowed for cross-origin requests (CORS and WebSocket). The server’s own origin (from webserver.url) and localhost at the listen port are always allowed. Defaults to * (wildcard) when not set, allowing any origin for multi-server support — cross-origin clients authenticate via Bearer tokens, not cookies. Set explicitly to restrict which origins can access the API. Wildcard CORS does not trust OAuth redirect callbacks.
CHATTO_WEBSERVER_OAUTH_REDIRECT_ORIGINS Comma-separated list of origins allowed for Chatto OAuth redirect callbacks when another Chatto frontend connects to this server. Use exact HTTPS origins, such as https://app.example.com, when you operate a known frontend. Set to * if you intentionally want any valid HTTPS Chatto frontend to connect. This is convenient for open federation-style alpha deployments, but it lets any HTTPS site start an authorization request and ask the user to approve sending an authorization code back to that site. See the Security guide for the risk tradeoff.
Built-in automatic TLS via Let’s Encrypt. When enabled, Chatto handles certificate provisioning and renewal automatically.
CHATTO_WEBSERVER_TLS_ENABLED Enable automatic TLS via Let’s Encrypt. Requires ports 80 and 443 (or custom ports configured below).
CHATTO_WEBSERVER_TLS_DOMAIN Domain name for the TLS certificate. Required when TLS is enabled.
CHATTO_WEBSERVER_TLS_EMAIL Email address for Let’s Encrypt notifications. Required when TLS is enabled.
CHATTO_WEBSERVER_TLS_CACHE_DIR Directory to cache TLS certificates.
CHATTO_WEBSERVER_TLS_HTTP_PORT Port for the HTTP server (ACME challenges and HTTPS redirect). Use a higher port if running without elevated privileges.
Metrics
Section titled “Metrics”CHATTO_METRICS_ENABLED Expose a Prometheus-compatible per-process metrics endpoint on a separate internal HTTP listener.
CHATTO_METRICS_BIND_ADDRESS Address to bind the metrics listener. Keep this on localhost unless a trusted internal network or sidecar needs direct scrape access.
CHATTO_METRICS_PORT Port for the metrics listener.
CHATTO_METRICS_PATH HTTP path for Prometheus scrapes.
CHATTO_CORE_SECRET_KEY 256-bit hex secret for HMAC-derived bearer-token and account-flow link verifiers. Generate with openssl rand -hex 32. Keep this stable across restores if you want sessions and pending links to survive.
Assets
Section titled “Assets”CHATTO_CORE_ASSETS_SIGNING_SECRET 256-bit hex secret for signing asset URLs. Generate with openssl rand -hex 32.
CHATTO_CORE_ASSETS_MAX_UPLOAD_SIZE Max upload size for images and non-video files (e.g., 25MB, 25 MiB). Videos use a separate limit — see CHATTO_VIDEO_MAX_UPLOAD_SIZE.
CHATTO_CORE_ASSETS_STORAGE_BACKEND Storage backend for file attachments. Values: nats, s3.
S3 Storage
Section titled “S3 Storage”Only used when storage_backend is set to s3. See the S3 Storage guide for setup instructions.
CHATTO_CORE_ASSETS_S3_ENDPOINT S3 endpoint URL (e.g., s3.amazonaws.com for AWS, or a custom endpoint for S3-compatible services).
CHATTO_CORE_ASSETS_S3_BUCKET S3 bucket name. Created automatically on startup if it doesn’t exist.
CHATTO_CORE_ASSETS_S3_PATH_PREFIX Optional object key prefix for all S3 assets. Leave empty to store objects at the bucket root.
CHATTO_CORE_ASSETS_S3_REGION AWS region. Optional for non-AWS S3-compatible services.
CHATTO_CORE_ASSETS_S3_ACCESS_KEY_ID S3 access key ID.
CHATTO_CORE_ASSETS_S3_SECRET_ACCESS_KEY S3 secret access key.
CHATTO_CORE_ASSETS_S3_USE_SSL Use HTTPS for S3 connections.
CHATTO_CORE_ASSETS_S3_PATH_STYLE Use path-style URLs instead of virtual-hosted. Required for most S3-compatible services (Cloudflare R2, Wasabi, Backblaze B2, etc.).
Image Cache
Section titled “Image Cache”CHATTO_CORE_ASSETS_CACHE_ENABLED Enable caching for resized images. Reduces CPU usage for repeated thumbnail generation.
CHATTO_CORE_ASSETS_CACHE_TTL Time-to-live for cached images. Supports durations like 7d, 1w, 168h.
CHATTO_NATS_REPLICAS Number of replicas for JetStream streams, KV buckets, and object stores. Must be an odd number (1, 3, or 5) for quorum. Set to 3 or 5 when running a NATS cluster for fault tolerance.
Embedded Server
Section titled “Embedded Server”CHATTO_NATS_EMBEDDED_ENABLED Enable the embedded NATS server. Set to false when connecting to an external NATS server.
CHATTO_NATS_EMBEDDED_PORT Embedded NATS server port. Leave unset or set to 0 for in-process only mode. Set to 4222 or another port to expose a TCP listener for NATS CLI/admin commands.
CHATTO_NATS_EMBEDDED_BIND_ADDRESS Embedded NATS server bind address.
CHATTO_NATS_EMBEDDED_HTTP_PORT NATS monitoring/stats HTTP port. Set to 0 to disable. Useful for debugging with the NATS dashboard.
CHATTO_NATS_EMBEDDED_DATA_DIR JetStream data directory for the embedded server.
CHATTO_NATS_EMBEDDED_AUTH_TOKEN Auth token for the embedded NATS server. When the embedded TCP port is enabled, Chatto derives matching nats.client defaults for CLI/admin commands unless you override them explicitly.
Client
Section titled “Client”CHATTO_NATS_CLIENT_URL NATS server URL to connect to when using external NATS or an exposed embedded TCP listener. Supports comma-separated URLs for cluster failover (e.g., nats://n1:4222,nats://n2:4222).
CHATTO_NATS_CLIENT_AUTH_METHOD NATS authentication method for external NATS or an exposed embedded TCP listener. Values: none, token, userpass, credentials, nkey.
CHATTO_NATS_CLIENT_TOKEN NATS auth token (when using token auth method). When explicitly set alongside embedded NATS, it must match CHATTO_NATS_EMBEDDED_AUTH_TOKEN.
CHATTO_NATS_CLIENT_USERNAME NATS username (when using userpass auth method).
CHATTO_NATS_CLIENT_PASSWORD NATS password (when using userpass auth method).
CHATTO_NATS_CLIENT_CREDENTIALS_FILE Path to .creds file (when using credentials auth method).
CHATTO_NATS_CLIENT_NKEY_SEED NKey seed (when using nkey auth method).
CHATTO_NATS_CLIENT_CA_CERT PEM-encoded CA certificate for verifying the NATS server’s TLS certificate. When set, the NATS client connection uses TLS.
Authentication
Section titled “Authentication”CHATTO_AUTH_DIRECT_REGISTRATION Enable direct (email/password) registration. When false, the registration page is hidden and the registration API returns 403. Users can still sign in via configured SSO providers.
CHATTO_AUTH_TOKEN_TTL Inactivity TTL for bearer auth tokens. Supports durations like 90d, 2160h. Successful validation refreshes the TTL; inactive tokens expire automatically.
External Login Providers
Section titled “External Login Providers”External login providers are configured as repeated [[auth.providers]] tables in chatto.toml.
Supported provider types are oidc, github, gitlab, google, and discord.
CHATTO_AUTH_PROVIDERS_<index>_<field> Counted environment-variable equivalent of repeated [[auth.providers]] tables. Indexes start at 0 and must not have gaps. Supported fields are ID, TYPE, LABEL, CLIENT_ID, CLIENT_SECRET, ISSUER_URL, SCOPES, REQUEST_EMAIL, and PROVIDER_OPTIONS_<KEY>.
For compatibility with older single-provider OIDC deployments, Chatto also accepts CHATTO_AUTH_OIDC_ENABLED, CHATTO_AUTH_OIDC_ISSUER_URL, CHATTO_AUTH_OIDC_CLIENT_ID, CHATTO_AUTH_OIDC_CLIENT_SECRET, and optional CHATTO_AUTH_OIDC_LABEL. These create one oidc provider with id = "oidc". Do not combine them with counted CHATTO_AUTH_PROVIDERS_<index>_* variables.
[[auth.providers]]id = "chatto-hub"type = "oidc"label = "Chatto Hub"issuer_url = "https://hub.chatto.dev"client_id = "..."client_secret = "..."Provider IDs are used in login URLs and external identity links, so do not change them after users link accounts through that provider.
See External Login Providers for callback URLs, provider-specific examples, and discovery behavior.
CHATTO_SMTP_ENABLED Enable SMTP email sending.
CHATTO_SMTP_HOST SMTP server hostname.
CHATTO_SMTP_PORT SMTP port. Common value: 587 (STARTTLS).
CHATTO_SMTP_TLS SMTP TLS policy. Use mandatory to require STARTTLS. Use opportunistic only when the SMTP server cannot support mandatory STARTTLS and plaintext fallback is explicitly acceptable.
CHATTO_SMTP_USERNAME SMTP username.
CHATTO_SMTP_PASSWORD SMTP password.
CHATTO_SMTP_FROM From address for outgoing emails.
Push Notifications
Section titled “Push Notifications”CHATTO_PUSH_ENABLED Enable Web Push notifications.
CHATTO_PUSH_VAPID_PUBLIC_KEY VAPID public key for Web Push. Generate with npx web-push generate-vapid-keys.
CHATTO_PUSH_VAPID_PRIVATE_KEY VAPID private key for Web Push.
CHATTO_PUSH_VAPID_SUBJECT VAPID subject identifier. Use an operator email address, optionally prefixed with mailto:, or an https: contact URL.
Video Processing
Section titled “Video Processing”CHATTO_VIDEO_ENABLED Enable server-side video processing and video uploads. When enabled, uploaded videos are transcoded into multiple quality variants for adaptive playback. Requires ffmpeg and ffprobe to be available on the server.
CHATTO_VIDEO_FFMPEG_PATH Path to the ffmpeg binary. If not set, Chatto looks for ffmpeg in PATH.
CHATTO_VIDEO_FFPROBE_PATH Path to the ffprobe binary. If not set, Chatto looks for ffprobe in PATH.
CHATTO_VIDEO_MAX_CONCURRENT Maximum number of videos to process concurrently. Higher values use more CPU and memory.
CHATTO_VIDEO_MAX_UPLOAD_SIZE Max upload size for video files (e.g., 100MB, 200 MiB). Only applies when video processing is enabled. Non-video files use CHATTO_CORE_ASSETS_MAX_UPLOAD_SIZE instead.
CHATTO_VIDEO_TEMP_DIR Directory for temporary files during transcoding. Defaults to the system temp directory.
LiveKit (Voice & Video Calls)
Section titled “LiveKit (Voice & Video Calls)”CHATTO_LIVEKIT_ENABLED Enable LiveKit voice and video call support. Requires a running LiveKit server.
CHATTO_LIVEKIT_URL LiveKit server WebSocket URL. Use ws:// for development, wss:// for production.
CHATTO_LIVEKIT_API_KEY LiveKit API key for authentication.
CHATTO_LIVEKIT_API_SECRET LiveKit API secret for signing JWT tokens. Keep this confidential.
CHATTO_LIVEKIT_WEBHOOK_URL URL where LiveKit sends webhook events. Defaults to {webserver.url}/webhooks/livekit.
CHATTO_LIVEKIT_SERVER_ID Unique identifier for this Chatto server, prefixed to deterministic LiveKit room names. This value must match across replicas of one Chatto server, and should differ only across different Chatto servers sharing the same LiveKit cluster. When empty, room names use the unprefixed format. The old CHATTO_LIVEKIT_INSTANCE_ID / livekit.instance_id name is still accepted as a deprecated alias.
CHATTO_LIVEKIT_INSTANCE_ID Deprecated alias for CHATTO_LIVEKIT_SERVER_ID / livekit.server_id. Prefer the server ID name in new deployments.
CHATTO_LIVEKIT_WEBHOOK_API_KEY API key that LiveKit uses to sign webhook requests. When multiple Chatto servers share a LiveKit cluster, the webhook signing key may differ from the per-server API key. Falls back to CHATTO_LIVEKIT_API_KEY when not set.
CHATTO_LIVEKIT_WEBHOOK_API_SECRET API secret for validating webhook signatures. Falls back to CHATTO_LIVEKIT_API_SECRET when not set.
Owners
Section titled “Owners”CHATTO_OWNERS_EMAILS Comma-separated list of email addresses that confer server-owner status. A user with any verified email matching the list gets full server access (including /admin routes). Only verified email addresses are matched.
Limits
Section titled “Limits”Server-wide resource limits. Use -1 for unlimited (the default), 0 to disable creation entirely, or any positive integer to cap.
CHATTO_LIMITS_MAX_USERS Maximum number of verified users on this server. Enforced at signup: when the verified-user count is already at the limit, new signups are rejected. Note that the check is non-atomic, so a burst of concurrent signups at the boundary can briefly overshoot by one or two.