Configuration reference
All runtime behavior is loaded from a validated TOML file. Unknown or missing required fields fail startup rather than silently selecting hidden behavior.
server
Listener address, public base URL, maximum body size, in-flight request limit, shutdown grace period, CORS origins, and credential policy.
routes
Prefixes or paths for API, web interface, watch page, embed player (embed, for example /embed), oEmbed endpoint (oembed, for example /oembed), streaming assets, liveness, readiness, and OpenAPI. Routes must be unique, absolute, and free of traversal components.
api
Default and maximum page sizes.
web
Enable flag, shell template, asset directory and mount route, site name, tagline, repository/documentation/support links, locale, time zone, brand color, dashboard reporting range, dashboard/job refresh intervals, page-size choices, and page cache policy.
database
SQLite URL, pool size, busy timeout, journal mode, and synchronous mode.
storage
Durable root, temporary root, original/stream/trash directory names, and deleted-media retention policy.
streaming
Independent cache policies for players, token redirects, playlists, segments, sources, and private assets, plus range-request support.
registration
Mode, optional administrator token/header, default quota, and account/API-key field limits.
browser_auth
Password pepper and Argon2id parameters; password limits; session signing key; absolute and idle TTLs; maximum sessions; cookie name/path/domain/security/HttpOnly/SameSite attributes; CSRF header; cleanup interval.
security
API-key prefix, pepper and Argon2 parameters; playback signing key and token lifetime.
uploads
Minimum/maximum source size, text and filename limits, fallback names and content type, default visibility, and accepted content types.
remote_imports
Enable flag, private-network policy, maximum size, request timeout, redirect cap, user agent, and system-proxy policy.
jobs
Worker concurrency, poll interval, lease duration, lease-renewal interval, maximum attempts, and retry base delay.
transcoding
FFmpeg/FFprobe paths, command timeout, HLS segment duration/format/version, output names and patterns, playlist flags, scaling, audio layout, thread count, original retention, upscale policy, extra arguments, and any number of rendition profiles.
analytics
Enable flag, viewer hash key, visitor/playback/session cookie settings, heartbeat controls, reporting limits, raw/session retention, cleanup interval, optional byte-event retention, and the qualified-view rule (qualified_view_seconds, recommended 30; qualified_view_minimum_fraction, recommended 0.5).
player
HTML template and optional hls.js URL.
observability
Tracing filter and JSON output selection.
protection
Per-client stream request rate and burst, playback-session rate, concurrent stream responses, per-response byte pacing for segments and originals, a global egress cap, cross-site (hotlink) blocking, whether viewers may fetch the original when HLS exists, and the trusted client-address header. Recommended values (example configuration): 30 requests/s with a burst of 300, 60 sessions/min, 16 concurrent streams, originals paced at 2.5 MB/s after a 16 MB burst, segments unpaced, hotlink blocking on, originals hidden once HLS renditions exist. 0 disables a limit. See Playback protection.
embed
Enable flag, origins allowed to frame the embed player (["*"] allows any site), and the default embed size used by oEmbed and the embed-code builder.
geolocation
Both fields are optional: database_path to a MaxMind DB country database (DB-IP Lite, GeoLite2 Country, or IPinfo Lite) and/or country_header naming a trusted CDN country header. Without either, countries are reported as unknown (ZZ).
See config/gulfstream.example.toml for every field and a complete set of values.