Self-Host Cliparr and Access It with Localtonet

Understand the Cliparr architecture before installing it

Cliparr is designed to create clips from Plex, Jellyfin, local files, and supported direct media URLs. Its editor can trim and fine-tune a range on a timeline, create or import subtitles, burn supported subtitles into an export, and produce video, audio-only, or GIF output.

The division of work between the server and browser matters. The self-hosted server handles media-server authentication, encrypted provider records, active playback discovery, and proxy work for media routes. Editing and export processing run in the browser. A local file is read directly by the browser rather than uploaded to Cliparr first. Plex, Jellyfin, and direct media URL sources can pass through Cliparr's media proxy so the browser can preview and export authenticated media.

Because processing happens in the browser, the documented Cliparr workflow does not require FFmpeg on the Docker host. The browser device still needs enough memory and compatible codecs for the selected source and output. A powerful server does not prevent a browser tab or mobile device from running out of memory during a large export.

Prepare the host, secrets, storage, and network binding

Cliparr's supported quick start uses Docker with Linux containers and the published image ghcr.io/techsquidtv/cliparr:latest. You need a stable application key, a persistent volume, an available host port, and a current browser. Plex and Jellyfin are optional because a local file can be used for the first editor test.

Review the current Cliparr repository and quick start before installation. The repository is also the primary entry point for Cliparr's provider, configuration, browser-support, reverse-proxy, and access-control guides.

Generate and retain the application key

Cliparr requires an APP_KEY containing a random secret of at least 32 characters. On a system with OpenSSL, the documented example is:

openssl rand -base64 32

Save the generated value in a password manager or another protected secret store before creating the container. Do not publish it, commit it to a repository, include it in screenshots, or paste it into support messages. Commands in this guide use a placeholder instead of a real secret.

Choose the Docker port binding based on the Localtonet client location

Docker's documented quick-start mapping, -p 7171:7171, normally publishes port 7171 on every host interface. Depending on the host firewall and network, that can make Cliparr reachable from the LAN or other connected networks before a tunnel is created.

If Localtonet will run on the same host as Docker, bind Cliparr to loopback with -p 127.0.0.1:7171:7171. The Localtonet client can then target 127.0.0.1:7171, while other LAN devices cannot connect directly through the host's private address.

If Localtonet will run on another device, loopback-only publication will not work because that other device cannot reach the Docker host's loopback interface. Publish Cliparr on a deliberately selected private interface, use the Docker host's private address as the tunnel target, and enforce suitable host firewall and network controls. Avoid exposing port 7171 on more interfaces than the deployment needs.

Use an address the container can actually reach

From inside the Cliparr container, localhost refers to the container itself. It does not automatically refer to a Plex or Jellyfin process elsewhere on the Docker host or LAN. Use a private address or container-network name that resolves and routes correctly from the Cliparr container.

Cliparr 3 requires explicit opt-in for loopback media-server URLs. Plex uses CLIPARR_ALLOW_LOOPBACK_PLEX_URLS=true, while Jellyfin uses CLIPARR_ALLOW_LOOPBACK_JELLYFIN_URLS=true. The Cliparr 3 release and configuration notes say to enable these only when every signed-in user is trusted. Private LAN server addresses continue to work without these flags.

Install Cliparr with Docker

The commands below use a loopback-only publication because that is the narrower choice when the Localtonet client will run on the same host. If your Localtonet client must run on another private device, replace this binding with a deliberately reachable private-interface publication and apply host controls before proceeding.

macOS or Linux shell

docker run -d \
  --name cliparr \
  -p 127.0.0.1:7171:7171 \
  -e APP_KEY="your-32-char-stable-random-secret" \
  -v cliparr-data:/data \
  ghcr.io/techsquidtv/cliparr:latest

PowerShell

docker run -d `
  --name cliparr `
  -p 127.0.0.1:7171:7171 `
  -e APP_KEY="your-32-char-stable-random-secret" `
  -v cliparr-data:/data `
  ghcr.io/techsquidtv/cliparr:latest

The named volume is created automatically when it does not already exist. Docker starts the container in detached mode under the name cliparr.

docker ps --filter name=cliparr
docker logs cliparr

Open http://localhost:7171 on the Docker host. Do not proceed to Localtonet until this endpoint works. A tunnel cannot repair a stopped container, an invalid key, a port conflict, or a provider address the container cannot reach.

Connect Plex, Jellyfin, or a local file

The official Cliparr site summarizes the source workflow, while the repository documentation links to current provider setup and account requirements. Provider access should be tested locally before the tunnel is introduced.

Plex requirements

Connect the Plex account through Cliparr and select the intended server. Current Cliparr 3 guidance states that live Plex session discovery requires a Plex server administrator account. Cliparr can then discover active playback sessions, open the current media, and begin clipping around the playback position.

Media sources are associated with the signed-in provider account. If a previously visible server disappears, verify that Cliparr is signed in using the account that added it.

Jellyfin requirements

Connect Jellyfin using an address reachable from the Cliparr container and the intended account. Regular Jellyfin accounts require Jellyfin 10.11 or newer for live session updates. With an older server, upgrade Jellyfin or connect an administrator account.

Configure the final Jellyfin address directly. Cliparr 3 rejects redirects to a different localhost address or port, including when loopback access has been enabled. A container-network address such as http://jellyfin:8096 is appropriate only if that hostname and port genuinely exist in your Docker environment.

Local video workflow

For the least complex test, choose Open Video and select a video from the device running the browser. The browser reads the file directly. This isolates the editor from provider authentication, playback discovery, and server-to-server networking.

Verify editing and export locally

Establish a known-good baseline before adding HTTPS and remote networking. A complete test confirms source loading, timeline interaction, playback, and at least one short export.

Cliparr can preserve source details, artwork, credits, and millisecond clip timing in supported video and audio containers. When valid provider data is available, supported exports can include IMDb, TMDB, and TVDB identifiers and critic or audience ratings. GIF exports do not include transcript metadata.

Audio-only output includes MP3, M4A/AAC, Ogg/Opus, FLAC, and WAV. Mix down to stereo is enabled by default in Cliparr 3. Surround audio is converted to stereo unless that option is disabled for a supported AAC or FLAC workflow. MP3, WAV, and Opus currently require mono or stereo.

Install and verify the Localtonet client on Debian or Ubuntu

This procedure intentionally covers one current, repeatable deployment path: the Localtonet DEB package on a supported x64 Debian or Ubuntu host. The current package requirements are systemd 247 or newer and OpenSSL 3, such as Debian 12 or Ubuntu 22.04 and newer. ARM64 packages and additional operating-system downloads are available in the Localtonet installation documentation, but package names must match the host architecture.

Download the current Debian or Ubuntu x64 package from our documentation page. The commands below assume the downloaded file is named localtonet-linux-x64.deb and that the terminal is open in the directory containing it.

sudo apt install ./localtonet-linux-x64.deb

Edit /etc/localtonet/auth-token as root, replace the package's placeholder with your real device token on one line, save the file, and then run:

sudo chmod 600 /etc/localtonet/auth-token
sudo localtonet --headless --authtoken-file /etc/localtonet/auth-token --check-config

After the check reports a valid configuration, start and inspect the service:

sudo systemctl enable --now localtonet.service
sudo systemctl status localtonet.service
sudo journalctl -u localtonet.service

For a future Localtonet package update, install the new package and restart the service:

sudo systemctl restart localtonet.service
sudo journalctl -u localtonet.service

Create and start the Localtonet HTTP tunnel

Once Cliparr works locally and the Localtonet client is connected, create an HTTP tunnel using the workflow in our HTTP tunnel documentation. HTTP and File Server process types can use a random subdomain, a custom subdomain where supported, or a custom domain. Select only options and relay servers currently displayed for your account.

The target address depends on where the client runs. When Docker and Localtonet share a host and Cliparr uses the loopback publication shown above, use 127.0.0.1 and port 7171. When the client runs elsewhere, use the Cliparr host's deliberately reachable private IP and port. In that second design, 127.0.0.1 would incorrectly refer to the Localtonet device itself.

Verify persistent connections and media routes

A successful page load proves only that an ordinary HTTP request reached Cliparr. Current Cliparr guidance says reverse-proxy paths must support persistent notification connections. Jellyfin communication uses WebSockets, while Plex-to-Cliparr and Cliparr-to-browser event updates use unbuffered server-sent events.

The supplied Localtonet evidence does not independently establish end-to-end behavior for every Cliparr WebSocket and server-sent-event path, client version, relay, or deployment. Verify these behaviors in the actual tunnel rather than inferring compatibility from the landing page:

• Open the assigned https:// URL from a separate device.
• Connect to the intended Plex or Jellyfin account.
• Start, pause, and stop playback, then watch whether sessions update promptly.
• Leave the page open long enough to detect dropped or repeatedly reconnecting notifications.
• Preview provider media and move the timeline range.
• Complete a short export and open the downloaded result.
• Repeat with subtitles if they are part of the intended workflow.

If the interface loads but sessions become stale, treat persistent-connection handling as unverified until the complete path works reliably. Review Cliparr's current reverse-proxy guidance from the official repository and inspect the Cliparr and Localtonet logs for disconnects.

Back up, restore, and update Cliparr safely

Routine container operation

Stopping and starting the existing container does not remove its named volume:

docker stop cliparr
docker start cliparr
docker logs cliparr

Stopping Cliparr leaves the Localtonet tunnel configuration intact, but the target remains unavailable until Cliparr starts again. Stopping the Localtonet client or tunnel makes the public URL unavailable while Cliparr can continue working locally.

Create a stopped-container volume backup

The following procedure is for a POSIX-compatible shell. It stops Cliparr so files in the named volume do not change while the archive is created. It writes cliparr-data-backup.tar.gz to the current directory by mounting the volume read-only in a temporary Alpine container.

docker stop cliparr

docker run --rm \
  -v cliparr-data:/volume:ro \
  -v "$PWD":/backup \
  alpine \
  sh -c 'tar -czf /backup/cliparr-data-backup.tar.gz -C /volume .'

docker start cliparr

Confirm that the archive exists and store it somewhere protected. Back up the exact APP_KEY separately in your secret manager. A restore requires both the volume contents and the original key if you want existing encrypted provider records to remain usable.

Restore the named volume

docker stop cliparr
docker rm cliparr

docker volume rm cliparr-data
docker volume create cliparr-data

docker run --rm \
  -v cliparr-data:/volume \
  -v "$PWD":/backup:ro \
  alpine \
  sh -c 'tar -xzf /backup/cliparr-data-backup.tar.gz -C /volume'

Recreate the Cliparr container using the same image configuration, port binding, volume mount, and saved APP_KEY. Then verify the local page, provider connections, a short export, and the public HTTPS workflow.

Perform a normal container update

A routine update replaces the container while preserving cliparr-data and APP_KEY. Take a stopped-container backup first, read the release notes for the destination version, and then pull and recreate the container.

docker pull ghcr.io/techsquidtv/cliparr:latest
docker stop cliparr
docker rm cliparr

docker run -d \
  --name cliparr \
  -p 127.0.0.1:7171:7171 \
  -e APP_KEY="your-original-stable-app-key" \
  -v cliparr-data:/data \
  ghcr.io/techsquidtv/cliparr:latest

If your deployment uses a controlled private-interface binding rather than loopback, recreate that same intended binding instead of copying the loopback example. Confirm that the new container remains running:

docker ps --filter name=cliparr
docker logs cliparr

Post-update verification should include all of the following:

• Open http://localhost:7171 on the host.
• Confirm that expected Plex or Jellyfin providers remain connected.
• Open a known local or provider source.
• Create and inspect a short export.
• Open the Localtonet HTTPS URL from another device.
• Test live session updates and a remote export.

Keep the destructive 2.x to 3.x migration separate

According to those release notes, original media, already downloaded clips, and subtitle style preferences are preserved outside the deleted database as applicable, but saved editing drafts are not. Reopening provider media may import the preferred supported subtitle track again, while local videos begin without subtitles.

Remembered provider logins created or renewed under Cliparr 3 last 30 days rather than one year. Existing remembered logins retain their previous expiration until renewed. Do not delete a current volume during an ordinary later update unless the release notes for that specific transition explicitly require it.

Troubleshoot each layer in order

The local page does not open

Check whether the container is running and inspect its logs:

docker ps --filter name=cliparr
docker logs cliparr

Confirm that Docker is using Linux containers, that the intended host binding was created, and that port 7171 was not already occupied. Verify http://localhost:7171 before changing any tunnel setting.

Plex or Jellyfin cannot connect

Confirm that the provider address is reachable from the Cliparr container, not only from the host browser. Replace an inappropriate localhost address with a valid private address or container-network name. Enable a provider-specific loopback variable only when the architecture requires it and every signed-in user is trusted.

Plex session discovery requires a server administrator account. Regular Jellyfin accounts require Jellyfin 10.11 or newer for live session updates. Configure Jellyfin's final address directly rather than relying on a redirect to another localhost port.

Sessions are missing, stale, or repeatedly reconnecting

Verify that playback is active and that Cliparr is signed in with the account that added the source. Disconnected servers can retain their last known sessions with a connection status, so a visible old session does not prove that the provider is currently connected.

If the problem appears only through the public path, test the WebSocket and server-sent-event behavior described earlier. A static page response does not validate those persistent notification channels.

The Localtonet service does not connect

Run the configuration check again without exposing the token, then inspect the service status and logs:

sudo localtonet --headless --authtoken-file /etc/localtonet/auth-token --check-config
sudo systemctl status localtonet.service
sudo journalctl -u localtonet.service

Confirm that the token file contains the intended device token on one line and is readable by the service under the packaged configuration. Keep its permissions at mode 600.

The public URL does not load

1. Confirm that Cliparr opens locally on port 7171.
2. Confirm that the Localtonet client is connected.
3. Confirm that the HTTP tunnel was started after it was created.
4. Verify the tunnel's local IP address and port.
5. If the client is on another machine, verify private-network reachability from that machine.
6. Use the assigned HTTPS URL instead of a guessed hostname.

Remember that 127.0.0.1 always refers to the machine on which the Localtonet client runs. It is the correct target only when that same machine can reach Cliparr on loopback.

Editing works locally but not remotely

Confirm that the remote browser uses the Localtonet https:// address. Test a local file separately from a provider source. If a local file works but Plex or Jellyfin fails, investigate provider authentication, media proxy reachability, and persistent connections rather than the basic editor.

A FLAC or large export fails

Cliparr documents a boundary-related FLAC limitation. Choose WAV or adjust the clip's start or end time. If Cliparr cannot read the end of a standalone FLAC file, shorten the selection to end before the unreadable area. Changing output format cannot recover source audio that Cliparr could not read.

For a large export, shorten the range and retry. Exports remain in browser memory, and WAV cannot exceed its 4 GiB file-size limit.

Plex subtitles are unavailable

Prefer SRT/SubRip or WebVTT where available. Other text subtitle formats may require Plex to convert them before Cliparr can use them. Some embedded text tracks become available only after the track is selected during Plex playback.

Secure a remotely accessible Cliparr deployment

A public HTTPS address provides secure transport and the browser context Cliparr requires for remote editing. It does not, by itself, authorize users. A difficult-to-guess or unpublished URL is not an access-control mechanism.

The supplied Cliparr evidence links to reverse-proxy and access-control guidance but does not establish that every Cliparr deployment has a built-in application login protecting the complete interface. Provider sign-in protects provider interactions, but it should not be assumed to protect every route or local-file workflow. Unless you have verified current Cliparr access controls for your deployed version, treat the public endpoint as exposed to anyone who obtains the URL.

Never expose the Localtonet device token, Cliparr application key, Plex credentials, Jellyfin credentials, provider tokens, or private media endpoints. If a credential is disclosed, revoke or rotate it through the system that issued it and update the deployment.

Recheck the complete workflow after updates or configuration changes. A short remote export, provider-session update, and local verification provide a stronger health check than a successful response from the home page.

Frequently asked questions