Source: https://cliparr.dev/docs/configuration/

Documentation

# Configuration

Environment variables, credential encryption, persistent data, and reverse proxy notes.

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.

APP\_KEY is part of your data

`APP_KEY` encrypts persisted provider credentials. Treat it like a secret backup item, not a disposable container variable.

## 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](https://cliparr.dev/docs/providers#automatic-session-updates) for recovery behavior and Jellyfin compatibility.

Add authentication at the proxy

Cliparr does not include a full user or permission system. Use an authenticated reverse proxy or private-access layer when you need to limit who can open the app.

## 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](https://cliparr.dev/docs/logging). For tags embedded into exported clips, see [Export metadata](https://cliparr.dev/docs/export-metadata).