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.
Web Server
Section titled “Web Server”CHATTO_WEBSERVER_URL Public URL of the instance, 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_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 instance’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-instance support — cross-origin clients authenticate via Bearer tokens, not cookies. Set explicitly to restrict which origins can access the API.
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.
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_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. Set to 0 to disable the TCP listener (in-process only).
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. Must match CHATTO_NATS_CLIENT_TOKEN when using token auth.
Client
Section titled “Client”CHATTO_NATS_CLIENT_URL NATS server URL to connect to. Supports comma-separated URLs for cluster failover (e.g., nats://n1:4222,nats://n2:4222).
CHATTO_NATS_CLIENT_AUTH_METHOD NATS authentication method. Values: none, token, userpass, credentials, nkey.
CHATTO_NATS_CLIENT_TOKEN NATS auth token (when using token auth method). Must match CHATTO_NATS_EMBEDDED_AUTH_TOKEN when using the embedded server.
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).
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 TTL for bearer auth tokens. Supports durations like 90d, 2160h. Tokens older than this are automatically invalidated.
CHATTO_AUTH_OIDC_ENABLED Enable OIDC sign-in (e.g. via Chatto Hub).
CHATTO_AUTH_OIDC_ISSUER_URL OIDC issuer URL. Used for discovery via /.well-known/openid-configuration.
CHATTO_AUTH_OIDC_CLIENT_ID OIDC client ID, obtained from your OIDC provider.
CHATTO_AUTH_OIDC_CLIENT_SECRET OIDC client secret.
CHATTO_AUTH_OIDC_LABEL Button label shown on the login page for the OIDC provider.
CHATTO_SMTP_ENABLED Enable SMTP email sending.
CHATTO_SMTP_HOST SMTP server hostname.
CHATTO_SMTP_PORT SMTP port. Common values: 587 (TLS), 465 (SSL), 25 (unencrypted).
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. Must be a mailto: or https: URL.
Video Processing
Section titled “Video Processing”CHATTO_VIDEO_ENABLED Enable server-side video processing. 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_INSTANCE_ID Unique identifier for this Chatto instance, prefixed to LiveKit room names. Required when multiple Chatto replicas share the same LiveKit cluster, so that webhook events can be routed correctly. When empty, room names use the unprefixed format.
CHATTO_LIVEKIT_WEBHOOK_API_KEY API key that LiveKit uses to sign webhook requests. When multiple Chatto replicas share a LiveKit cluster, the webhook signing key may differ from the per-replica 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.
CHATTO_ADMIN_EMAILS Comma-separated list of instance admin email addresses. Only verified email addresses are matched.