Muximux: A Homelab Dashboard That Puts Stubborn Apps Inside the Frame

The problem Muximux was written for: apps that refuse to be framed

Most self-hosted apps ship with `X-Frame-Options: DENY`, which means a browser will not render them inside an iframe. That single header is why so many homelab dashboards end up as a wall of links and status tiles rather than a place you actually work. The README states the project's position plainly: most dashboards point at your apps, Muximux makes them actually embed.

The target user is narrow and the README says so. Muximux is for someone who spends the day working inside self-hosted apps, not glancing at widgets on a landing page. Click Sonarr and Sonarr opens inside the dashboard. Click Plex and Plex does too. The README also names the dashboards you probably already run (Homepage, Homarr, Organizr, Dashy) and tells you that if one of them fits your workflow, you probably do not need to read further. That is an unusually direct piece of positioning for a project README, and it is worth taking at face value: this is not a general-purpose dashboard that happens to have a proxy bolted on. The proxy is the product.

How the embedding proxy actually works

Three mechanisms are described in the README. First, the proxy strips the framing headers that block embedding. Second, it rewrites paths in HTML, CSS and JavaScript so that requests an app makes with absolute paths still resolve through the proxy rather than escaping to the origin. Third, it patches `fetch()` and `XMLHttpRequest` at runtime, which is what the README credits with making heavy single-page apps behave the way they do when opened directly.

That third step is the interesting one. Header stripping alone gets a static page to render; it does nothing for an app whose frontend was built assuming it owns the root of the domain. By patching the two browser request APIs, the proxy intercepts calls that would otherwise bypass it. The README does not describe how the patch is injected or what happens when an app uses a request path the patch does not cover, and that silence is worth noticing.

The rest of the stack is visible in the repository layout and `go.mod`. The module is `github.com/mescon/muximux/v3` and it depends on `github.com/caddyserver/caddy/v2`, so the optional gateway is embedded Caddy rather than a hand-rolled reverse proxy. The frontend lives under `web/` and is built with Vite, which the Dockerfile confirms. The backend is Go, split across `cmd/` and `internal/`. The README's summary is one binary, one port, one YAML config file.

Installing Muximux with Docker Compose and a first app

The repository ships a `docker-compose.yml` whose header comment gives the usage directly: run `docker compose up -d`. The service uses the image `ghcr.io/mescon/muximux:latest`, publishes port 8080, and mounts `./data` into `/app/data` for persistent state.

services:
  muximux:
    image: ghcr.io/mescon/muximux:latest
    container_name: muximux
    init: true
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data

Three environment variables are named in the compose comments for direct overrides: `MUXIMUX_DATA`, `MUXIMUX_LISTEN` and `MUXIMUX_CONFIG`. The same comment block describes a second, more useful pattern: any `${VAR}` written in `config.yaml` is replaced with the value of that environment variable. That is how you keep a secret out of the file.

client_secret: ${OIDC_CLIENT_SECRET}

Start the stack with `docker compose up -d`, then open port 8080. The README and screenshots describe an onboarding wizard with steps for welcome, security, an app catalog, selection, style and themes, so the first run is a guided flow rather than a blank config file. The repository also carries `config.example.yaml` at the top level if you would rather read the full shape of the configuration before starting. If you enable `tls.domain` or `gateway_sites`, the compose file notes that the embedded Caddy binds 80 and 443 for ACME, and those port mappings are commented out by default. There is also a documented escape hatch for hosts that cannot bind privileged ports: set `server.gateway_listen: ":8443"` in `config.yaml` and expose 8443 instead, which suits setups fronted by Cloudflare Tunnel or an upstream Traefik that terminates TLS.

The embedded Caddy gateway and the Docker socket trade-off

The compose file documents an optional mount of the Docker socket so that Muximux can scan the daemon for running containers, surfaced under Settings then Discovery from 3.1.0 onward. The comment says read-only is an option, and read-only is the one to take. A dashboard that can enumerate containers is convenient; a dashboard with a writable socket is a much larger blast radius, and the container already runs with `cap_drop: ALL` and `no-new-privileges:true` in the shipped compose file. Those two settings are a clear signal about the project's posture, and handing it a writable socket would work against them.

The gateway itself is where the upgrade story gets interesting. The compose comments describe a migration path: if you have a legacy gateway Caddyfile from 3.0.x, you mount it once, and the first boot under 3.1.0 converts it to `server.gateway_sites:` in YAML, backs the original up with a `.pre-3.1.0.bak` suffix, rewrites `config.yaml`, and then the Caddyfile mount is no longer needed. That is a one-shot migration with a backup, which is the right shape. It is also a one-way door in practice: once `config.yaml` has been rewritten, the YAML is the source of truth and the old file is a backup, not a fallback.

What Muximux does not do, and when it is the wrong tool

The README is explicit about the omissions. Muximux does not pull live widgets from Sonarr or qBittorrent, and it does not offer a freeform grid editor for arranging resizable widgets on a canvas. If either of those is what you want from a dashboard, this is the wrong project and the README will tell you so before you install anything.

The proxy is a second, sharper limitation. Rewriting paths and patching `fetch()` and `XMLHttpRequest` is a general technique that will not be perfect for every application. An app that constructs URLs in a way the patch does not intercept, or that relies on a header the proxy alters, can load and then misbehave in ways that are hard to attribute. The README presents the proxy as the reason the project exists and does not publish a compatibility list, so the honest position is that you have to try your own apps through it. Treat the proxy as something to validate per app, not as a guarantee.

There is also a maintenance consideration that is easy to miss. The README carries an AI disclosure stating that Muximux is developed with significant AI assistance (Claude Code), with all code reviewed, tested and approved by the maintainer before shipping. That is disclosed rather than hidden, which is to the project's credit, but it does mean the review capacity of a single maintainer is the throughput limit for the whole codebase. The repository does carry CI, CodeQL, SonarCloud and Codecov badges, so there is automated checking in place alongside that review.

Muximux against Homepage and Homarr

The README names the alternatives itself, which makes the comparison unusually easy to state. Homepage and Homarr are the two it singles out. The difference is directional: those tools are built around pulling live information out of your services and arranging it, while Muximux is built around putting the services themselves on screen. The README says Homepage is lovely at live widgets and that Homarr is built around a freeform grid editor. Neither of those is a criticism; they are simply a different answer to the question of what a homelab landing page is for.

Organizr and Dashy round out the list the README gives. If your habit is to open the dashboard, check a few statuses and then click through to a tab anyway, a widget-oriented dashboard is the better fit and Muximux will feel like it is missing features. If your habit is to open the dashboard and stay there, working in Sonarr and Plex for the next hour, the embedding proxy is the feature the other tools do not have. That is the whole decision, and the README frames it that way rather than pretending to compete on breadth.

Licence, upgrade cost and what to check before you commit

Muximux is licensed GPL-2.0, per the repository's `LICENSE` file and the badge in the README. For self-hosted homelab use that is unremarkable. It matters if you intend to redistribute a modified binary or embed the code in something you ship, because GPL-2.0 carries obligations that permissive licences do not. This is a description of the licence, not legal advice; read the licence text if your use is anything other than running it on your own hardware.

Upgrade cost is dominated by two things. The first is the 3.0.x to 3.1.0 gateway migration described above, which is automatic but rewrites your configuration, so a backup of `./data` before the first boot on a new major version is cheap insurance. The second is the release cadence: v3.4.1 on 2026-09-05, v3.4.0 on 2026-09-03, and v3.3.3 on 2026-07-29. That is a project moving quickly enough that pinning to a tag rather than `latest` is a reasonable default for anyone who does not want a surprise mid-week. The last push to the repository was on 2026-09-09.

Before you commit, verify the things the README cannot verify for you. Check that your apps render through the proxy rather than merely loading. Check which port the embedded Caddy wants if you enable TLS, and whether 80 and 443 are free on the host. And check whether the Docker socket mount is something you actually want, given that discovery is a convenience rather than a requirement.

Editorial conclusion

Adopt Muximux if your homelab routine means living inside Sonarr, Radarr or Plex and the X-Frame-Options wall is what stops you consolidating. Skip it if you want a canvas of live widgets, since the README says Muximux deliberately does not pull them. Before committing, verify three things on your own host: that the Docker socket mount is read-only if you enable discovery, that you have picked a gateway_listen port that does not collide with anything already on 80 or 443, and that every app you care about still renders correctly through the proxy rather than only loading.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. mescon/Muximux on GitHub
4. README
5. Releases