Build a persistent Muxarr container, verify media access, and add remote browser access
Muxarr is a self-hosted media-management application for cleaning unwanted audio and subtitle tracks, standardizing track metadata, and automating processing alongside Sonarr and Radarr. In this guide, we install Muxarr with Docker Run, configure persistent storage and media mounts, complete the first-run wizard, and verify the application locally. Only after the local deployment works do we connect it to an HTTP tunnel with Localtonet. This keeps application troubleshooting separate from remote-access configuration and makes each stage easier to validate.
What Muxarr does
Muxarr helps administrators reduce unnecessary tracks in self-hosted media libraries. It can remove unwanted audio tracks such as commentary or unneeded dubs, remove subtitles that do not match a profile, and clean metadata attached to media tracks. It supports Matroska files such as .mkv and .webm, as well as MP4-family files including .mp4 and .m4v.
For MKV files, Muxarr uses tools from MKVToolNix. For other supported containers, it uses FFmpeg with stream copying. The documented workflow remuxes tracks instead of re-encoding the video, so the media is not subjected to a lossy video conversion. Metadata-only changes can use mkvpropedit without a full remux. Muxarr also validates an output file before replacing the original, and the original remains untouched if validation fails.
Sonarr and Radarr integration is optional. When configured, Muxarr can use them for original-language detection and webhook-based automation when new media is imported. You can also create different profiles for different directories, define language priorities, limit tracks per language, and preview proposed changes before placing files into the processing queue.
Prerequisites and deployment decisions
This tutorial uses the published container image ghcr.io/kirovair/muxarr:latest. The image is documented for Linux AMD64 and Linux ARM64 systems. You need a working Docker installation, a host directory for persistent Muxarr configuration, and one or more host directories containing the media that Muxarr will inspect.
Decide which host paths you will use before starting the container. The container path /config is Muxarr's fixed location for its database and configuration. Media can be mounted at /media or another container path of your choosing. If you add multiple media mounts, keep their container paths stable because Muxarr profiles and Sonarr or Radarr path mappings can depend on those paths.
| Setting | Purpose | Documented value or behavior |
|---|---|---|
/config |
Muxarr database and configuration | Mount a persistent host directory at this fixed container path. |
/media |
Media library | A common container path, although additional or differently named media mounts are supported. |
8183:8183 |
Web interface | Publishes the Muxarr web application on host TCP port 8183. |
PUID and PGID |
File permissions | Set these to the user and group IDs that should access the mounted host directories. |
UMASK |
Permissions for written files | Optional. The documented default is 022; 002 is an example for group-writable libraries. |
Muxarr is designed to validate output before replacing an original file, but it still operates on your media library. Maintain an independent backup, begin with a limited test directory, review the preview carefully, and confirm that the container user has only the permissions it genuinely needs.
Install Muxarr with Docker Run
The following sequence follows Muxarr's documented Docker Run deployment. Replace the example host paths, timezone, user ID, and group ID with values that match your host. Do not run the unmodified placeholders as though they were real directories.
Prepare persistent host directories
Create or select a host directory for Muxarr's database and configuration, plus the media directory that the container should access. Confirm that the user represented by your chosen PUID and PGID can read the media and can write wherever your intended Muxarr workflow requires it.
Start the Muxarr container
Run the documented container command after substituting the host paths and identity values. The port mapping exposes the web interface on TCP port 8183, while the two volume mappings preserve configuration and provide access to the media library.
Open the local web application
From a browser that can reach the Docker host, open http://your-ip:8183, replacing your-ip with the host's reachable address. If the browser is running directly on the Docker host, use an appropriate local address for that system.
Complete the first-run wizard
Follow the wizard to set an optional username and password, optionally connect Sonarr and Radarr, create a profile with your media directories and language rules, scan the library, preview changes, and queue selected files for processing.
docker run -d \
--name=muxarr \
-e TZ=Europe/Amsterdam \
-e PUID=1000 \
-e PGID=1000 \
-p 8183:8183 \
-v /path/to/muxarr/config:/config \
-v /path/to/your/media:/media \
--restart unless-stopped \
ghcr.io/kirovair/muxarr:latest
The values in that command are examples from the documented installation. Set TZ to your timezone and set PUID and PGID to the numeric IDs appropriate for your host. Muxarr documents defaults of UTC for TZ, 888 for PUID, 888 for PGID, and 022 for UMASK. The explicit values in the example override some of those defaults.
Configure Sonarr, Radarr, and media profiles
Sonarr and Radarr are optional integrations rather than installation requirements. If you connect them, use Muxarr's setup interface and provide the connection information requested by the current version. Credentials, API keys, and service addresses depend on your environment, so they should not be copied from an example or exposed in a public article.
Path consistency is particularly important when Muxarr and an Arr application run in separate containers. Each application may see the same host directory under a different container path. Use the path-mapping controls provided by the applications to ensure that a file reported by Sonarr or Radarr resolves to the corresponding mounted path inside Muxarr. Do not change established container media paths casually after creating profiles and mappings.
Create a conservative first profile for a small test directory. Define the language rules and track limits that match that collection, scan it, and inspect the per-file preview. This is safer than applying a broad profile to an entire library before you understand how the available track metadata is interpreted. After validating the output with your normal media player, you can expand the profile or create additional profiles for other collections.
The documented endpoint is /api/stats and authentication uses an X-Api-Key header. Consult the examples under Muxarr's Settings and API interface for the current configuration. Never place the API key in a public URL, screenshot, article, or client-side script.
Verify Muxarr locally before remote access
A tunnel cannot repair a container that is stopped, a port that is not published, or a service that cannot read its mounted data. Verify the local deployment first. Confirm that the Muxarr interface loads at http://your-ip:8183, that the setup wizard completes, and that the expected media directories appear when creating a profile.
Next, scan a limited directory and inspect its library results. Preview at least one file and verify that the proposed language and track changes match your profile. If you process a test file, play the result and confirm that the intended audio and subtitles remain available. Check file ownership and permissions on the host afterward, especially if other media applications need to modify the same files.
If the browser cannot open Muxarr locally, troubleshoot Docker, host networking, and the container logs before continuing. The public Localtonet address should be added only after the local endpoint is reliable.
Upgrade notes for older Muxarr installations
Older Muxarr installations may store the database under /data rather than /config. For an existing deployment, keep the same host appdata directory and change only its container destination from /data to /config. Do not move the media mounts while making this change because profiles and Arr path mappings may reference their existing container paths.
If the appdata folder is empty because no persistent directory was mounted, or because an older version ignored a /config mount, the database may be inside a Docker volume. The documented migration approach is to stop the container and copy the contents of /data into the intended host appdata folder before removing the old container.
docker cp muxarr:/data/. /path/to/appdata/Replace the destination placeholder with the correct existing host directory. Verify that the copied database and configuration are present before removing anything. Nothing should be assumed about an older installation's storage layout without checking its actual mounts.
Provide remote HTTP access with Localtonet
Once Muxarr works locally, we can expose its web interface through an HTTP tunnel with Localtonet. Our client application establishes an outbound connection to a Localtonet relay server, so this workflow does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address. The HTTP tunnel points to the local Muxarr IP address and TCP port 8183, then provides a public HTTPS address.
Install and run our client on the Docker host or another device that can reach the Muxarr endpoint. If the client runs on the same host, target the local address that successfully reaches Muxarr. If it runs on another device, use the Docker host address that is reachable from that device. Select the relay server or region from the current dashboard rather than copying a hardcoded server code.
Install and run the Localtonet client
Install the Localtonet client on a device that can reach the verified Muxarr web service on port 8183.
Authenticate or select the client device
Use the device-specific token through the supported client workflow, then select that connected device in the dashboard. Keep the token private and never include it in commands, screenshots, or documentation.
Select an available relay server
Choose a currently available server or region from the dashboard. Availability can vary, so do not rely on a server code copied from an older tutorial.
Create an HTTP tunnel for Muxarr
Configure the local target with the IP address that reaches Muxarr and port 8183. Choose the applicable HTTP process type from the current dashboard. Random Sub Domain, Custom Sub Domain, and Custom Domain process types all serve content at a public HTTPS address, subject to current availability and configuration requirements.
Start the tunnel
Creating a tunnel does not start it. Press Start and wait until the selected client and tunnel are connected.
Test the assigned public address
Open the assigned HTTPS URL from a network outside the local LAN and confirm that the Muxarr sign-in or application page loads. Stop or delete the tunnel when remote access is no longer required.
For the current dashboard workflow, consult our Localtonet HTTP tunnel documentation. The public endpoint remains available only while the selected client device is connected and the tunnel is running.
A public URL makes the Muxarr interface reachable from the internet. Configure Muxarr's optional username and password before starting public access, protect Sonarr and Radarr credentials, apply least privilege to media mounts, and avoid exposing API keys. Review the current access-control options available to your environment and stop the tunnel when it is not needed.
Frequently asked questions
Which port does Muxarr use?
The documented Docker setup publishes Muxarr on TCP port 8183 with the mapping 8183:8183. The local interface is then available at http://your-ip:8183.
Are Sonarr and Radarr required?
No. They are optional integrations for original-language detection and webhook automation. You can install Muxarr, create profiles, scan media, preview changes, and queue processing without connecting either application.
Does Muxarr re-encode video?
Its documented processing uses MKVToolNix for MKV files and FFmpeg stream copying for other supported containers. Tracks are remuxed rather than subjected to lossy video re-encoding, while some metadata-only changes can be applied without a remux.
Why should I verify Muxarr locally before creating a tunnel?
Local verification separates container, port, permission, and media-mount problems from tunnel configuration. If http://your-ip:8183 does not work from a device that should reach it, resolve that problem before configuring remote access.
Does creating a Localtonet tunnel make it active immediately?
No. After creating the HTTP tunnel, you must press Start. The tunnel is available only while the selected client device is connected and the tunnel is running.
Do I need router port forwarding for remote Muxarr access with Localtonet?
No. Our client establishes an outbound connection to a relay server, so the documented tunneling workflow does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
Connect your verified Muxarr service with Localtonet
After Muxarr loads locally and your authentication and media permissions are ready, create an HTTP tunnel that targets the working service on port 8183.
Get Started Free →
