Cliparr only needs a few settings in production: a stable APP_KEY and a persistent data directory.
| Variable | Description | Default |
|---|---|---|
| APP_KEY | Required secret for credential encryption. Must be at least 32 characters long.Required | - |
| PORT | Internal port for the Express server. | 7171 prod / 3000 dev |
| CLIPARR_DATA_DIR | Directory for SQLite storage. | /data |
| CLIPARR_LOG_LEVEL | Server log level. Supports trace, debug, info, warning, error, and fatal. Defaults to debug in development and info in production. | debug/info |
| CLIPARR_LOG_FORMAT | Production server console log format. Development console logs are always JSON. | json dev / pretty prod |
| CLIPARR_LOG_FILE | Optional path for a rotating server log file. Relative paths resolve from the server working directory. | - |
| CLIPARR_LOG_FILE_FORMAT | Optional log file format. Defaults to CLIPARR_LOG_FORMAT when set, otherwise json. | json |
| CLIPARR_LOG_FILE_MAX_SIZE | Maximum size for each rotating server log file. Supports kb, mb, and gb suffixes. | 10mb |
| CLIPARR_LOG_FILE_MAX_FILES | Total number of rotating server log files to keep, including the active file. | 5 |
| CLIPARR_ALLOW_LOOPBACK_PLEX_URLS | Allow Plex URLs that resolve to loopback only for the initial configured origin, including redirects returning to it. Enable only if you trust every authenticated user: they can configure arbitrary loopback hosts and ports. Other origins remain blocked from reaching loopback. | false |
| CLIPARR_ALLOW_LOOPBACK_JELLYFIN_URLS | Allow Jellyfin URLs that resolve to loopback only for the initial configured origin, including redirects returning to it. Enable only if you trust every authenticated user: they can configure arbitrary loopback hosts and ports. Other origins remain blocked from reaching loopback. | false |
Plex and Jellyfin connections support private LAN servers. Loopback addresses such as localhost, 127.0.0.1, and ::1 require the corresponding CLIPARR_ALLOW_LOOPBACK_*_URLS opt-in. Enable these flags only if every authenticated user is trusted: users can configure arbitrary loopback hosts and ports on the Cliparr host.
The loopback exception applies only to the initial configured server origin (scheme, hostname, and port), including redirects returning to it. Redirects to another origin cannot reach loopback, even with the flag enabled. Cloud metadata, link-local, unspecified, and multicast addresses remain blocked.
Behavior change: Earlier Jellyfin loopback opt-ins also allowed redirects to other loopback origins. Those redirects are now rejected. Configure the final Jellyfin origin directly if your setup relied on such a redirect.
Reverse proxies
When running behind Caddy, Nginx, Traefik, or another reverse proxy, preserve the Host header and pass X-Forwarded-Proto. Cliparr trusts loopback, link-local, and private-LAN proxy ranges directly in the app, so typical same-network proxy setups do not need extra app configuration.
The dashboard receives live updates over a long-lived server-sent event (SSE) response at /api/media/live. Allow that response to stream without buffering or caching. Cliparr sends a heartbeat every 15 seconds; proxy idle timeouts must allow these connections to stay open between heartbeats.
If a reverse proxy sits between Cliparr and your media server, it must also support Plex’s SSE notifications or Jellyfin’s WebSocket connection. The browser connects to Cliparr for updates; Cliparr maintains the provider connections. Delayed updates or repeated reconnects can indicate proxy buffering or timeouts. See Automatic session updates for recovery behavior and Jellyfin compatibility.
HTTPS and browser APIs
The editor uses browser WebCodecs. Supporting browsers require a secure context, which means HTTPS in production. Local development on localhost and 127.0.0.1 also counts as secure for this browser requirement.
Data directory
The default container data directory is /data. In production, mount that path to a volume so SQLite state and encrypted provider credentials survive updates.
For diagnostics and file log settings, see Logging. For tags embedded into exported clips, see Export metadata.