Build a single-binary homelab workspace, verify it locally, then make the dashboard available from outside your network
Muximux is a self-hosted dashboard designed to open homelab applications inside one browser interface. Version 3 ships as a single static binary with an embedded frontend, uses one YAML configuration file, and does not require a separate database or web server. This guide explains an evidence-bounded installation workflow, local configuration and verification, embedded-application behavior, safe operation, and troubleshooting. After the dashboard works on your local network, we show how to expose its HTTP listener with Localtonet without configuring inbound router port forwarding, changing firewall rules, setting up a VPN, or requiring a public IP address.
📋 What's in this guide
What Muximux does in a homelab
Muximux is a self-hosted web dashboard for people who actively work inside several homelab applications. Instead of acting only as a page of bookmarks, it can open applications inside dashboard panes. This allows tools such as media managers, monitoring interfaces, and other internal web applications to remain available within a single browser tab.
Muximux v3 is a rewrite built around a Go backend with its frontend embedded in the executable. The project describes the deployment model as one binary, one port, and one YAML configuration file. It does not require PHP, a separate runtime, an external database, or a separate web server for the basic dashboard. Muximux also supports Docker, but this guide focuses on the static-binary installation path.
The dashboard includes built-in authentication, guided onboarding, real-time application health monitoring over WebSocket, split views, themes, a command palette, application and group organization, and an optional embedding proxy. Configuration can be changed through the built-in graphical interface, so editing YAML manually is not required for ordinary setup. Because the deployment state is stored in one configuration file, backing up that file is central to migration and recovery.
Embedding proxy versus remote-access tunnel
Muximux's embedding proxy and a Localtonet HTTP tunnel solve different problems. The embedding proxy helps another web application render inside a Muximux pane. It can remove iframe-blocking headers, rewrite paths in HTML, CSS, and JavaScript, and intercept browser requests used by complex single-page applications.
A Localtonet HTTP tunnel provides a public route to the Muximux web listener. Our client creates an outbound connection from the machine running Muximux, or from another machine that can reach it, to a Localtonet relay server. The resulting public HTTPS address forwards requests to the selected local IP address and port.
Enabling the Muximux embedding proxy does not make the dashboard reachable from the internet. Creating a Localtonet tunnel does not automatically make every application iframe-compatible. Configure each layer for its own purpose.
Prerequisites and decisions before installation
Choose a machine that can stay online whenever you want to use the dashboard. Muximux must be able to reach the homelab applications you add, while the Localtonet client must be able to reach the Muximux listener. Both processes may run on the same machine, but that is not required.
Before downloading a release, identify the operating system and processor architecture of the target machine. Select a release asset that explicitly matches both. Do not assume that a binary built for a similarly named platform or a different processor architecture will work.
You should also decide where the executable, configuration, and backups will live. Use an account with only the file and network permissions the service needs. Avoid running the process with administrative or root privileges unless a documented platform requirement makes that necessary.
- A supported release asset matching the host operating system and CPU architecture.
- A persistent directory in which the service account can read the executable and maintain its configuration.
- Network access from the Muximux host to each homelab application that the dashboard will monitor or proxy.
- An available local TCP port for the Muximux HTTP listener.
- A browser on the same machine or LAN for initial verification.
- A current Localtonet client and device-specific authentication token for the later remote-access stage.
The verified project material establishes that Muximux supports a single static binary and Docker, but the supplied installation evidence does not establish exact asset filenames, archive formats, operating-system commands, default directories, service-manager commands, bind addresses, or a default port. We therefore do not invent them. Use the asset and startup syntax shown for the exact release you download, then substitute the listener actually configured or reported by that release throughout this guide.
Choose the local listener deliberately
The listener consists of an IP address and a TCP port. A loopback address limits direct access to the Muximux host. A LAN address or all-interface bind can permit direct connections from other devices, depending on the host firewall and network policy. Because the verified evidence does not define a universal default, record the effective listener shown by your configuration or startup output rather than assuming one.
If the Localtonet client runs on the same machine as Muximux, a loopback listener may be sufficient. If the client runs on another device, Muximux must listen on an address reachable from that client device, and local firewall policy must permit that internal connection.
Install Muximux as a single binary
A binary deployment is useful when you want a small runtime footprint without adding a container engine. The project also publishes a Docker deployment, but the two installation methods should not be mixed casually. Pick one ownership model for the process, configuration file, listener, updates, and backups.
The release identified in the supplied evidence is v3.4.0. It is described as a security release built with a patched Go toolchain and with vulnerability scanning restored as a blocking CI gate. Releases change over time, so inspect the current release information before installation rather than treating a version mentioned in an article as permanently current.
Select the correct official release asset
Open the Muximux release page, identify the release you intend to deploy, and choose the asset matching the host operating system and processor architecture. Read the release notes for security notices, migration requirements, and known compatibility changes. Do not rename or execute an asset until you are confident it is intended for your platform.
Verify the downloaded artifact
Follow the artifact-verification procedure published for that release and the project's security policy. The available evidence confirms that the repository includes security guidance and artifact-verification information, but it does not provide the exact verification command or checksum filename. Do not substitute a guessed command or trust an unofficial mirror.
Place the binary in a persistent location
Extract the archive if the chosen asset is packaged, then place the executable in a directory controlled by the account that will run Muximux. Make the executable runnable using the normal procedure for your operating system. Keep application data and configuration on persistent storage rather than in a temporary download directory.
Start Muximux with the documented release syntax
Use the startup invocation documented for the exact asset and release. During the first run, keep the process attached to a terminal or visible through your process manager so that you can inspect startup output. Record the effective IP address, port, configuration location, and any warnings. The supplied evidence does not establish a universal command-line syntax, so this guide intentionally does not fabricate one.
Open the local onboarding interface
From a browser that can reach the listener, open the HTTP address reported or configured during startup. Complete the guided onboarding flow, including its security stage, before considering remote publication. If the page does not load, stop here and use the local troubleshooting section before creating a tunnel.
Run it as a managed service after validation
A foreground process is useful for first-run diagnostics, but an always-available dashboard normally needs supervision. After local testing, configure the operating system's service manager to run the verified executable under a dedicated account, use the intended working directory, preserve the configuration file, restart according to your operational policy, and capture logs.
The repository contains a service-related file, but the supplied evidence does not establish its supported operating systems, installation destination, user account, or exact commands. Review that file before adapting it. Do not copy service paths blindly, especially if your executable or configuration is stored elsewhere.
Configure the dashboard and embedded applications
Muximux provides a built-in GUI for its settings, so the safest first configuration path is the onboarding wizard and application forms. Direct YAML editing is useful for version-controlled administration or migration, but a guessed field name or indentation error can prevent startup. When you do edit YAML, stop the process if required by the documented workflow, create a backup, validate the result, and preserve file ownership.
Configure authentication first
Muximux documents built-in username and password authentication, forward authentication through systems such as Authelia or Authentik, and OIDC. Select an authentication model before exposing the listener. Built-in authentication is the most direct option for a standalone setup. Forward authentication or OIDC may be appropriate when your homelab already has a trusted identity layer.
An unauthenticated dashboard can disclose application names, internal service structure, health information, and navigation paths. It may also provide access to embedded applications according to their own session and authentication behavior. Do not assume that an obscure public URL is an access-control mechanism.
Add applications and verify ordinary iframe behavior
Add one application at a time using its URL as reachable from the Muximux host or from the browser, depending on how the application is configured to open. Test navigation, sign-in, static resources, API requests, and WebSocket-driven updates where applicable. A page that displays its login screen is not necessarily fully compatible. Complete a representative task inside the pane before marking the application as working.
If an application allows iframe embedding and its URL is reachable from every browser that will use Muximux, ordinary iframe mode may be enough. This can be straightforward on the LAN but fail remotely when an embedded URL contains a private hostname or private address that the remote browser cannot resolve or route to.
Enable the embedding proxy only where needed
For an application that rejects iframe rendering or breaks because it expects root-relative paths, Muximux can enable its embedding proxy for that application. The documented configuration uses the application's proxy setting, represented as proxy: true in YAML. Through a path based on the application's slug, Muximux forwards the backend and rewrites relevant headers and resources.
This proxy can be particularly important for remote access. When the browser receives an embedded private-LAN URL directly, it still needs a route to that address. When a compatible application is served through Muximux's embedding proxy, the browser interacts through the Muximux origin while the Muximux host reaches the backend internally.
| Application mode | Where the backend must be reachable | Remote-access consideration |
|---|---|---|
| Link opens separately | The user's browser must reach the configured application URL | A private LAN URL will normally remain unreachable to an off-site browser unless it has a separate access path |
| Direct iframe | The user's browser must reach and be permitted to frame the application | Private names, private addresses, and iframe-blocking headers can prevent remote use |
| Muximux embedding proxy | The Muximux host must reach the backend | The browser accesses the proxied application through Muximux, subject to application compatibility and authentication |
| Muximux dashboard through Localtonet | The Localtonet client must reach the Muximux listener | Only the selected Muximux HTTP target is published by that tunnel |
Do not enable the embedding proxy indiscriminately. Muximux will make requests to the selected backend and transform content so it can operate through the dashboard. Add only services you administer, keep backend authentication enabled where practical, and test sensitive functions before relying on the embedded view.
Finish the initial dashboard setup
Organize applications into meaningful groups, select icons, choose a navigation layout, and configure light, dark, or custom themes as needed. Muximux also supports pinning applications directly to the navigation bar, and release v3.4.0 documents the YAML representation pinned: true. These interface choices do not change network reachability, but they can make frequently used tools easier to find.
Use health monitoring to identify applications that Muximux cannot currently reach. A healthy dashboard process does not guarantee that every backend is available. Conversely, one unavailable application should not be mistaken for a failure of the dashboard listener or the Localtonet tunnel.
Verify Muximux locally before publishing it
Remote-access troubleshooting becomes much easier when the local service has already passed a structured test. Verify from the Muximux host first, then from another LAN device if your intended bind configuration permits LAN access.
Confirm the process stays running
Check the terminal, service manager, or process monitor. Review startup output for configuration errors, permission failures, or a port conflict. Record the actual listener rather than relying on an assumed default.
Load the dashboard from the host
Open the configured local address in a browser on the Muximux machine. Confirm that the interface loads completely, not merely that the TCP port accepts a connection.
Test authentication in a private session
Use a private browsing window to prove that unauthenticated users receive the intended sign-in flow. Sign in, sign out, and confirm that protected content is not retained unexpectedly after logout.
Open each configured application
Test direct iframe applications and embedding-proxy applications separately. Watch for blank panes, failed logins, missing assets, redirect loops, browser-console errors, or WebSocket failures.
Test from the Localtonet client device
If the Localtonet client will run on another machine, open the Muximux listener from that machine using the exact local IP address and port you plan to enter in the tunnel. A tunnel cannot repair local routing or firewall failures between the client and its target.
Save a backup of the working YAML configuration after this test. Protect it according to the sensitivity of its contents and keep at least one copy outside the live application directory. The evidence establishes a single-file configuration model, but it does not establish whether every deployment stores secrets in plain text, encrypted form, or external references. Treat the file as sensitive unless you have verified otherwise for your release and authentication mode.
Expose the working Muximux dashboard with Localtonet
Once Muximux works locally, an HTTP tunnel can publish its web listener. The Localtonet client establishes an outbound connection to one of our relay servers. This means you do not need inbound router port forwarding, firewall changes, VPN setup, or a public IP address for this workflow.
The tunnel points to the local IP address and port where Muximux is already listening. If both processes run on the same host, that may be a loopback target. If they run on different machines, use the Muximux host address that is reachable from the Localtonet client. Do not enter an address that works only from your own laptop unless the client runs there.
Install and run the Localtonet client
Install the current Localtonet client for the operating system on a device that can reach the verified Muximux listener. Keep the client running for as long as remote access is required. Use the current installation information provided by our platform rather than an unverified command copied from an older guide.
Authenticate the intended device
Use the device-specific authentication token assigned through Localtonet. Treat the token as a credential, do not place it in screenshots or public configuration, and do not reuse a guessed or unrelated token.
Select an available relay server
Choose a currently available server or region from the dashboard. Available values can vary, so this guide does not hardcode a server code or claim that every location is available on every plan.
Create an HTTP tunnel for Muximux
Select an HTTP tunnel and enter the exact local IP address and port proven during local verification. HTTP is appropriate because the target is the Muximux web interface. Do not select File Server, proxy-server, VPN, UDP, or raw-port functionality for this HTTP dashboard workflow.
Choose the public address process type
HTTP tunnels can use Random Sub Domain, Custom Sub Domain, or Custom Domain. All three serve the target at a public HTTPS address. Availability can vary, and exact custom-domain DNS instructions must be checked against current documentation before changing DNS records.
Start the tunnel and test its assigned URL
Creating the tunnel does not start it. Press Start, wait for the tunnel and selected client to be connected, then open the assigned public URL in a private browser session on a network outside the homelab. Confirm authentication, navigation, application panes, and sign-out behavior.
For the current dashboard workflow and field descriptions, consult our Localtonet HTTP tunnel documentation. Use the current interface values for your account instead of relying on hardcoded regions, plan assumptions, or old screenshots.
The public address works only while the selected Localtonet client device is connected and the tunnel is running. Creating a saved tunnel configuration alone does not make Muximux available. If the host sleeps, the client exits, local connectivity fails, or the tunnel is stopped, remote access ends.
Perform a real off-site test
Testing the public URL from inside the same LAN is useful, but it does not reproduce every remote condition. Use a mobile connection or another external network and a private browser session. Verify that the login page appears before dashboard content, that successful sign-in works, and that each important application loads.
Pay special attention to applications configured as direct iframes. Their private URLs may have worked on the LAN but remain unreachable from an off-site browser. Where appropriate and compatible, configure Muximux's embedding proxy so the Muximux host reaches the backend on behalf of the browser. Alternatively, provide each backend with its own deliberately secured access method. Do not expose additional services merely to hide an iframe error.
Security and routine operations
A homelab dashboard is a high-value navigation point because it reveals what services exist and can bring several administrative interfaces into one place. Treat publishing it as a security decision, not only a connectivity task.
Use layered authentication
Enable one of Muximux's supported authentication methods before starting the public tunnel. Use unique credentials and least-privilege roles where your selected mode supports them. Keep authentication enabled on sensitive backend applications as well. A dashboard login should not automatically be interpreted as authorization for every embedded service.
If you use forward authentication or OIDC, verify the complete redirect and callback flow through the final public address. The supplied evidence confirms those authentication categories but does not establish provider-specific callback paths, environment variables, header rules, or Localtonet-specific OIDC settings. Follow the exact configuration for your identity provider and Muximux release instead of guessing.
Keep Muximux current
Release v3.4.0 demonstrates why updates matter. Its release notes identify earlier 3.3.x builds that used a Go standard library version affected by published vulnerabilities, including a path-resolution issue relevant to the embedding proxy. The updated release was built on a patched toolchain and restored vulnerability scanning as a CI gate.
Before upgrading, back up the YAML configuration, read every intervening release note, verify the new artifact, stop the managed process cleanly, replace the binary using your platform's safe procedure, and restart it. Re-run local and remote verification after the change. Keep the previous verified binary and configuration backup available until the new version passes testing, unless a security notice advises against rollback.
Control the tunnel lifecycle
Start the tunnel only when remote access is needed if your workflow does not require continuous availability. Stop it when maintenance begins or when you want to suspend public access. Delete obsolete tunnels so that old configurations do not create confusion later. Remember that stopping Muximux and stopping the Localtonet tunnel are separate actions.
Back up configuration and document dependencies
Keep a protected copy of the YAML configuration and document the release version, listener, service account, working directory, authentication mode, backend application addresses, and whether each application uses direct iframe mode or the embedding proxy. Do not store Localtonet device tokens in that document.
A useful recovery test is to restore the binary and backed-up configuration onto an isolated machine, start it using the release's documented syntax, and confirm that the interface and application definitions return. Some backend sessions or identity-provider settings may still require additional recovery work.
Troubleshooting Muximux and Localtonet access
The binary does not start
Confirm that the asset matches the operating system and processor architecture. Check whether an archive still needs extraction, whether the executable has the required platform permission, and whether the service account can read the binary and configuration. Review startup output for malformed YAML, an unavailable working directory, or a listener conflict.
If the operating system blocks an unrecognized download, verify the artifact using the project's documented procedure before deciding whether to allow execution. Do not disable system protections globally.
The process runs, but the local page does not load
Recheck the reported listener. A process bound only to a loopback address will not accept connections addressed to a LAN interface. A service bound to another address will not necessarily answer on the hostname you expected. Confirm that the configured port is the port the process actually opened and that another process did not claim it.
Test from the Muximux host before testing from another device. If host-local access works but LAN access does not, investigate the bind address, local firewall, VLAN policy, and routing between the two devices.
The Localtonet tunnel is connected, but the public URL fails
Verify that the selected Localtonet device can open Muximux using the exact IP address and port saved in the tunnel. If it cannot, correct the local route or listener first. Confirm that the tunnel itself has been started, not merely created, and that the selected client remains connected.
If Localtonet and Muximux run on the same host, verify whether the target should use the effective loopback listener or another local address. If they run on separate hosts, do not use the Muximux machine's loopback address because loopback on the client refers to the client itself.
The dashboard loads remotely, but embedded applications are blank
Determine whether the failing application is a direct iframe or uses the Muximux embedding proxy. A direct iframe may point to a private hostname or address unavailable to the remote browser, or the backend may send iframe restrictions. Test the application URL directly from the remote browser to distinguish routing from framing behavior.
For a compatible application, enable the Muximux embedding proxy and test again. Inspect browser diagnostics and Muximux logs for missing resources, redirects, authentication failures, or WebSocket problems. Complex applications can change their frontend behavior between releases, so compatibility may also depend on the versions of both products.
Login redirects loop or return to the wrong address
This commonly indicates that the application or identity provider has an external-address, callback, forwarded-header, or secure-cookie expectation that does not match the public URL. The supplied evidence does not establish universal Muximux settings for every identity provider, so compare the final public HTTPS address with the provider's registered callback and the exact Muximux authentication documentation for your release.
Muximux works until the host restarts
A manually started binary does not necessarily start with the operating system. Configure an appropriate service manager after the foreground installation has been validated. Make sure its account, working directory, configuration path, environment, and network dependencies match the successful manual run. Review service logs after reboot rather than assuming the process started.
The public URL suddenly becomes unavailable
Check the two independent processes. First confirm that Muximux is running and reachable locally. Then confirm that the Localtonet client is connected and the HTTP tunnel is running. Also check whether the host entered sleep mode, changed local address, lost network access, or restarted without restoring one of the services.
Frequently asked questions
Does Muximux require Docker?
No. The project documents both Docker and a single static binary as deployment methods. The binary includes the frontend and does not require PHP, a separate web server, an external database, or other runtime dependencies for the basic deployment.
What port does Muximux use by default?
The supplied verified evidence does not establish a universal default port or bind address. Use the listener configured or reported by the exact release you install. Enter that same verified IP address and port when creating the Localtonet HTTP tunnel.
Does Localtonet expose every application listed in Muximux?
The HTTP tunnel exposes the selected Muximux listener. Direct iframe or link-out applications may still require the remote browser to reach their own URLs. Applications routed through Muximux's compatible embedding proxy can be fetched by the Muximux host and presented through the dashboard path.
Is the Muximux embedding proxy the same as a Localtonet tunnel?
No. The embedding proxy helps applications operate inside Muximux panes by rewriting headers and paths. A Localtonet tunnel creates a public route to the local Muximux HTTP listener through an outbound client connection.
Do I need router port forwarding or a public IP address?
No. The Localtonet client establishes an outbound connection to our relay server, so this workflow does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
Does creating the tunnel make it available immediately?
No. A tunnel must be started after it is created. It remains available only while the selected Localtonet client is connected and the tunnel is running. It can later be stopped or deleted from the dashboard.
Should I disable Muximux authentication because the public URL is hard to guess?
No. URL obscurity is not authentication. Enable built-in authentication, forward authentication, or OIDC before remote exposure, and retain appropriate authentication on sensitive backend applications.
Can the Localtonet client run on a different machine from Muximux?
Yes. The client can target a service on or reachable from its device. When the two processes run on different machines, Muximux must listen on an internal address reachable from the client, and local routing and firewall policy must allow the connection.
Access your verified Muximux dashboard with Localtonet
Finish Muximux onboarding, enable authentication, prove the dashboard and embedded applications locally, then create an HTTP tunnel that targets the confirmed listener. With the client connected and the tunnel started, you can use the assigned public HTTPS address without opening an inbound router port.
Get Started Free →
