config.toml
Reference for server/config.toml. Grouped by section.
Top level
Section titled “Top level”| Key | Default | Notes |
| -------------- | ------- | ----- |
| development | true | Enables /debug pprof endpoints and looser timeouts. Set false in production. |
[server]
Section titled “[server]”| Key | Default | Notes |
| ----------------- | ----------------------------- | ----- |
| poll_interval_minutes | 1 | Helix poll interval used by SERVER_MODE=poll for live detection and title tracking. |
[download]
Section titled “[download]”Recording behaviour. See Recording for narrative.
| Key | Default | Notes |
| ------------------------- | -------- | ----- |
| max_concurrent | 5 | Cap on parallel recordings across the server. |
| preferred_quality | "1080" | Target HLS variant. "1080", "720", "480", "360", "audio_only". |
| segment_concurrency | 4 | Parallel HLS segment fetches per recording. |
| network_attempts | 5 | Retry budget for generic network failures. |
| server_error_attempts | 5 | Retry budget for Twitch 5xx. |
| cdn_lag_attempts | 3 | Retry budget when a segment isn't on the CDN yet. |
| auth_refresh_attempts | 2 | Retry budget for expired playback tokens. |
| max_gap_ratio | 0.01 | Tolerated fraction of dropped segments before "incomplete" badge. |
| strict | false | If true, any gap fails the recording. |
| enable_av1 | false | Allow AV1 variants. |
| disable_hevc | false | Refuse HEVC variants. |
| max_restart_gap_seconds | 120 | Stream-drop window for appending to the same VOD. |
| max_part_bytes | 0 | Split into a new part once the current part reaches this many bytes (segment boundary). 0 disables; negative values clamp to 0. |
| max_part_seconds | 0 | Split into a new part once the current part reaches this many seconds. 0 disables; negative values clamp to 0. |
| max_part_count | 1024 | Maximum parts produced by configured size/duration splitting. |
| signed_url_ttl_hours | 168 | Maximum lifetime of the signed per-part download_url in recording-webhook payloads; enabled recording auto-delete can cap it sooner. 0 disables signed download URLs. |
[storage]
Section titled “[storage]”| Key | Default | Notes |
| ------------ | --------- | ----- |
| type | "local" | "local" or "s3". |
| local_path | "./data"| Used when type = "local". |
[storage.s3]
Section titled “[storage.s3]”Used only when [storage].type = "s3".
| Key | Default | Notes |
| ---------------- | ------- | ----- |
| endpoint | (empty) | S3-compatible endpoint URL. Empty means AWS S3. |
| bucket | (empty) | |
| region | (empty) | |
| access_key | (empty) | |
| secret_key | (empty) | |
| use_path_style | (unset) | Force path-style addressing. Custom endpoints default to path-style. |
[scheduler]
Section titled “[scheduler]”| Key | Default | Notes |
| ----------------------------------------- | ------- | ----- |
| enabled | true | Master switch for the scheduled-task runner. |
| eventsub_interval_minutes | 10 | EventSub quota-snapshot cadence. |
| eventsub_reconcile_interval_minutes | 60 | Periodic full reconcile of EventSub subscriptions. |
| category_art_interval_minutes | 1440 | Backfill box_art_url and igdb_id on categories from Helix /games. |
| category_metadata_interval_minutes | 1440 | Backfill category descriptions from IGDB games with a known igdb_id. |
| token_cleanup_interval_minutes | 60 | Drop expired Twitch app tokens. |
| session_cleanup_interval_minutes | 120 | Drop expired user session tokens. |
| fetch_logs_retention_days | 14 | Retention sweep for the Helix fetch-log table. |
| webhook_event_payload_retention_days | 7 | Trims the stored EventSub payload column. |
| event_logs_retention_days | 14 | Retention sweep for debug + info event-log rows. |
| recordings_retention_interval_minutes | 60 | Cadence of the per-schedule auto-delete sweep (time_before_delete). 0 disables. |
| recording_webhook_delivery_retention_days | 30 | Prunes terminal (delivered/rejected/failed) recording-webhook outbox rows. 0 disables. |
[logging]
Section titled “[logging]”| Key | Default | Notes |
| -------------- | ---------- | ----- |
| log_to_file | false | Mirror logs to a file in log_dir in addition to stderr. |
| log_dir | "./logs" | Directory for log files. Created on first write. |
| log_level | "debug" | debug, info, warn, error. |
[postgres]
Section titled “[postgres]”Pool tuning. Used only when DATABASE_DRIVER=postgres.
| Key | Default | Notes |
| ------------------------- | ----------- | ----- |
| max_conns | 25 | |
| min_conns | 5 | |
| max_conn_lifetime_ms | 1800000 | 30 min. |
| max_conn_idle_time_ms | 300000 | 5 min. |
| health_check_period_ms | 30000 | 30 s. |
[health]
Section titled “[health]”| Key | Default | Notes |
| --------- | ------- | ----- |
| enabled | true | Exposes unauthenticated GET /api/v1/health (200 on DB ping success, 503 on failure). The bundled Docker healthcheck depends on this. |