Feature Flags

Feature flags let admins enable or disable experimental features server-wide or for individual users. This allows testing new functionality before it’s ready for everyone.

How flags work

Each feature flag has:

• A default state (enabled or disabled) that applies to all users
• Optional per-user overrides that take precedence over the default

Resolution order:

1. Per-user override (if set) — wins
2. Server-wide default — fallback

Managing flags

Admin UI

Go to Settings > Feature Flags in the admin panel. From here you can:

• Toggle the server-wide default for any flag
• Set per-user overrides (enable a feature for specific testers)
• Clear per-user overrides to revert to the default

API

# List all flags
curl http://localhost:3000/v1/feature-flags \
  -H "Authorization: Bearer $TOKEN"

# Toggle default
curl -X PATCH http://localhost:3000/v1/feature-flags/{key}/default \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

# Set per-user override
curl -X POST http://localhost:3000/v1/feature-flags/{key}/overrides \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user-id", "enabled": true}'

Available flags

Player flags

Flag	Default	Description
unified_osd_web	Enabled	Unified on-screen display for the web player
unified_osd_appletv	Disabled	Unified OSD for Apple TV
unified_osd_androidtv	Disabled	Unified OSD for Android TV

Podcast flags

Flag	Default	Description
podcasts_enabled	Enabled	Core podcast features (subscribe, browse, play, progress)
podcasts_premium_playback	Disabled	Chapters, transcripts, sleep timer, trim silence
podcasts_management	Disabled	Queue, downloads, OPML import/export, smart playlists
podcasts_sync	Disabled	gPodder sync, recommendations, listening stats

Local development override

During development, you can override any flag by appending a query parameter to the URL:

https://dubby.example.com/?flag_unified_osd_web=false

This is useful for testing without changing server state. The query parameter takes precedence over both the server default and per-user overrides.

Audit logging

All flag changes are recorded in the audit log as config_change events. The specific operation is stored in the resource field:

• config:feature_flag.create — New flag created
• config:feature_flag.update_default — Server-wide default changed
• config:feature_flag.set_override — Per-user override set
• config:feature_flag.clear_override — Per-user override removed
• config:feature_flag.delete — Flag deleted

Stability expectations

Feature flags indicate different levels of readiness:

• Enabled by default — Stable, ready for general use. The flag exists to allow disabling if issues arise.
• Disabled by default — Experimental. May have bugs, incomplete UI, or missing functionality. Enable at your own risk.