Configuration reference

Kinosail accepts configuration from built-in defaults, Owner settings, a YAML file, and environment variables. The higher source wins.

Choose a source

Use the Owner settings page for values that you want to change in the app. Use YAML or environment variables for deployment-owned values.

The precedence order is:

environment > YAML > Owner settings (GUI) > built-in default

Kinosail reads the file named by KINOSAIL_CONFIG_FILE. If that variable is empty, the Server can use kinosail.yaml below its data directory. The example file is kinosail.example.yaml. Copy it to kinosail.yaml and set only the values that you own.

If YAML or an environment variable supplies a value, the Owner interface shows that value as managed and read-only. Resetting a managed value cannot change it. An omitted YAML value does not lock the corresponding Owner setting.

The paths.data value is resolved before stored Owner settings load. This lets a YAML or environment value select the directory that contains persisted configuration.

File and environment rules

• YAML must contain version: 1.
• YAML uses nested keys, such as playback.mode under playback.
• List values use YAML lists. Environment list values use a JSON array, such as [".","Shows"].
• A YAML secret can use a <key>_file value, such as token_file. The path is relative to the YAML file unless it is absolute.
• An environment secret can use a variable ending in _FILE. The file must be regular and no larger than 16 KiB.
• A direct secret variable and its _FILE form cannot both be set.
• _FILE is valid only for secret settings.
• Unknown keys, malformed values, and invalid cross-field combinations stop configuration loading.
• Settings marked “restart” take effect after a Server restart. Other settings are live or are applied by their owning operation.

An Owner change to logging.level takes effect immediately. A value managed by YAML or the environment needs a Server restart after that external source changes.

Do not place secrets in a committed YAML file. Prefer a mounted secret file or the Owner settings flow. Secret values are never returned by the configuration API.

Compose and application settings

The table lists application-process variables. Compose only passes variables explicitly declared in the chosen Compose files; setting an arbitrary variable in .env does not forward it. Host mount/binding variables such as KINOSAIL_MEDIA_PATH, KINOSAIL_BACKUP_PATH, KINOSAIL_BIND, and KINOSAIL_PORT configure Compose itself. Read .env.example alongside compose.yaml and any overrides.

Settings

The following table describes typed application settings. Use the running configuration API and the source definitions for the exact inventory of your installed version. A blank default means that the feature is not configured by default.

Enum values and validation

• playback.mode: automatic, direct, or compatible.
• playback.subtitles: on or off.
• transcoding.quality: automatic, speed, or quality.
• transcoding.accelerator: none, auto, vaapi, qsv, cuda, videotoolbox, rkmpp, v4l2m2m, amf, or mf.
• transcoding.codec: auto, h264, hevc, av1, or vp9.
• scanning.frequency: default, off, 5m, 15m, or 1h.
• remote.mode: off or https.

Remote HTTPS requires a DuckDNS domain and token plus an exact https://<domain>.duckdns.org auth.url. Enabling DLNA requires dlna.url. SCIM requires both its token and a future expiration time. MCP requires all five MCP OAuth values and a resource URL ending in /mcp.

integrations.jellyfin.enabled is false when it is unset. Setting it to true requires a valid trusted HTTPS value. Kinosail rejects the configuration before it exposes Jellyfin routes when trusted HTTPS is missing.

The Owner settings flow is the preferred setup. The historical tls.duckdns key now stores every supported trusted HTTPS provider. Its name remains for automatic upgrade compatibility.

A deployment-managed deSEC value is one secret JSON object:

{"provider":"desec","domain":"myhome.dedyn.io","token":"REDACTED_PROVIDER_TOKEN","address":"192.168.1.10","termsAccepted":true}

provider is duckdns or desec. domain is the lowercase subdomain label for DuckDNS. It is a lowercase full hostname for deSEC.

address must be a private IPv4 address or a local hostname that resolves to one private IPv4 address. termsAccepted records acceptance of the Let’s Encrypt subscriber agreement. Store the complete object through the environment variable _FILE form or another protected secret source.

Kinosail still accepts the previous DuckDNS object without provider. It treats that object as duckdns and requires no Owner action.

LAN trusted HTTPS requires TLS. It cannot run with public HTTPS remote mode. Follow Connect devices for the Owner workflow and privacy effects.

Owner-managed configuration API

Owners can inspect configuration with GET /api/v1/configuration. Use PUT /api/v1/configuration/{key} to save an editable value and DELETE to reset it to the next source. A managed key returns a conflict instead of changing state. See the API reference for authentication and the live schema.

Source of truth

This page follows internal/configuration/configuration.go, internal/configuration/parse.go, and kinosail.example.yaml. The application tests the example YAML and precedence rules during its configuration test suite.

The supported public HTTPS Compose override sets remote.gateway=true and adds a restricted public gateway container using the same image as the Server. The main application serves public requests only over a private Unix socket. Set this only with that deployment; an ordinary direct binary listener has no gateway process isolation. Owner device management is separate from remote.mode and is explicitly enabled and paired through Settings → Manage while away. See the remote-access guide.