unshackle/docs/ADVANCED_CONFIG.md

Advanced & System Configuration

This document covers advanced features, debugging, and system-level configuration options.

serve (dict)

Configuration for the integrated server that provides CDM endpoints (Widevine/PlayReady) and a REST API for remote downloading.

Start the server with:

unshackle serve                          # Default: localhost:8786
unshackle serve -h 0.0.0.0 -p 8888      # Listen on all interfaces
unshackle serve --no-key                 # Disable authentication
unshackle serve --api-only               # REST API only, no CDM endpoints
unshackle serve --remote-only            # Only expose remote service session endpoints

CLI Options

Option	Default	Description
-h, --host	127.0.0.1	Host to serve from
-p, --port	8786	Port to serve from
--caddy	false	Also serve with Caddy reverse-proxy for HTTPS
--api-only	false	Serve only the REST API, disable CDM endpoints
--no-widevine	false	Disable Widevine CDM endpoints
--no-playready	false	Disable PlayReady CDM endpoints
--no-key	false	Disable API key authentication (allows all requests)
--debug-api	false	Include tracebacks and stderr in API error responses
--debug	false	Enable debug logging for API operations
--remote-only	false	Only expose remote service session endpoints (health, services, search, session)

Configuration

• api_secret - Secret key for REST API authentication. Required unless --no-key is used. All API requests must include this key via the X-Secret-Key header.
• compression_level - Compression level for API payloads (manifests, cache, cookies). 0=off, 1=fast, 6=balanced, 9=max. Default: 1.
• session_ttl - Session inactivity timeout in seconds. Each request resets the timer. Default: 300.
• max_sessions - Maximum concurrent sessions before the oldest is evicted. Default: 100.
• services - Optional global service allowlist. Only these service tags are exposed. If omitted, all services are available.
• devices - List of Widevine device files (.wvd). If not specified, auto-populated from the WVDs directory.
• playready_devices - List of PlayReady device files (.prd). If not specified, auto-populated from the PRDs directory.
• users - Dictionary mapping user secret keys to their access configuration:
  • devices - List of Widevine devices this user can access
  • playready_devices - List of PlayReady devices this user can access
  • username - Internal logging name for the user (not visible to users)
  • services - Optional per-user service allowlist. Effective access is the intersection of global and per-user allowlists.

Server-side dl defaults

Any key accepted by /api/download (see docs/API.md) can also be declared directly under serve: and the REST API will treat it as a default. Per-request bodies still win. Use this to raise concurrency, force best_available, etc. without each client repeating the values:

serve:
  api_secret: "..."
  users: { ... }
  downloads: 4              # parallel tracks per job
  workers: 16               # threads per track
  best_available: true
  no_proxy_download: false

Layering: built-in defaults < serve.* overrides < service-specific defaults < request body.

For example,

serve:
  api_secret: "your-secret-key-here"
  compression_level: 1
  session_ttl: 300
  max_sessions: 100
  # services:           # global allowlist (optional)
  #   - EXAMPLE1
  #   - EXAMPLE2
  users:
    secret_key_for_jane: # 32bit hex recommended, case-sensitive
      devices: # list of allowed Widevine devices for this user
        - generic_nexus_4464_l3
      playready_devices: # list of allowed PlayReady devices for this user
        - my_playready_device
      username: jane # only for internal logging, users will not see this name
      # services:        # per-user allowlist (optional)
      #   - EXAMPLE1
    secret_key_for_james:
      devices:
        - generic_nexus_4464_l3
      username: james
  # devices can be manually specified by path if you don't want to add it to
  # unshackle's WVDs directory for whatever reason
  # devices:
  #   - 'C:\Users\john\Devices\test_devices_001.wvd'
  # playready_devices:
  #   - '/path/to/device.prd'

REST API

When the server is running, interactive API documentation is available at:

• Swagger UI: http://localhost:8786/api/docs/

See API.md for full REST API documentation with endpoints, parameters, and examples.

---

max_concurrent_downloads (int)

Maximum number of /api/download jobs the serve queue manager will execute in parallel. Each job runs the full dl pipeline (authenticate, fetch tracks, decrypt, mux) in its own worker subprocess. This is independent of serve.downloads, which controls parallel tracks inside a single job. Default: 2.

max_concurrent_downloads: 4

---

download_job_retention_hours (int)

How long completed, failed, or cancelled download jobs remain queryable via /api/download/jobs/{job_id} before the periodic cleanup loop drops them. Default: 24.

download_job_retention_hours: 48

---

debug (bool)

Enables comprehensive debug logging. Default: false

When enabled (either via config or the -d/--debug CLI flag):

• Sets console log level to DEBUG for verbose output
• Creates JSON Lines (.jsonl) debug log files with structured logging
• Logs detailed information about sessions, service configuration, DRM operations, and errors with full stack traces

For example,

debug: true

---

debug_keys (bool)

Controls whether actual decryption keys (CEKs) are included in debug logs. Default: false

When enabled:

• Content encryption keys are logged in debug output
• Only affects content_key and key fields (the actual CEKs)
• Key metadata (kid, keys_count, key_id) is always logged regardless of this setting
• Passwords, tokens, cookies, and session tokens remain redacted even when enabled

For example,

debug_keys: true

---

set_terminal_bg (bool)

Controls whether unshackle should set the terminal background color. Default: false

For example,

set_terminal_bg: true

---

update_checks (bool)

Check for updates from the GitHub repository on startup. Default: true.

---

update_check_interval (int)

How often to check for updates, in hours. Default: 24.

---

title_cache_enabled (bool)

Enable or disable title metadata caching globally. Default: true.

---

title_cache_time (int)

Title cache duration in seconds. Default: 1800 (30 minutes).

---

title_cache_max_retention (int)

Maximum cache retention in seconds, used as fallback when the upstream API fails. Default: 86400 (24 hours).

---

unicode_filenames (bool)

When false, replaces non-ASCII characters in output filenames with ASCII equivalents. Default: false.

---

ipinfo_api_key (str)

Optional ipinfo.io token. When set, unshackle uses the ipinfo.io Lite endpoint for IP/geolocation lookups instead of the unauthenticated fallback.

---

tmdb_api_key (str)

Optional TMDB API key, used for metadata enrichment and IMDb/TMDb tagging.

---

simkl_client_id (str)

Optional Simkl client ID for metadata lookups.

---

decrypt_labs_api_key (str)

Optional Decrypt Labs API key, used by services that integrate with the service.

---