Repository navigation
docker discovery
Docker discovery connects Muximux to a Docker daemon. Muximux can then list the running containers and propose them as apps. It also keeps their URLs current when container IPs change across restarts. The feature is off by default, because it needs read access to the Docker socket.
- Scan: lists running containers. For each one, it proposes a name, icon, URL, port, and group, with confidence ratings (high / medium / low).
- Import: adds the chosen containers in one click, as apps in the menu, gateway subdomains, or both. Each row picks a routing mode: Direct URL, internal Proxy, or Gateway domain.
- Refresh: a background poller (a task that runs on a timer, default 60s) looks up each tracked container on the daemon again. If the container's IP changes, it rewrites the saved URL. When gateway-site URLs change, Caddy (the web server built into Muximux) reloads once per tick (one run of the poller).
-
Auto-import (optional): set
discovery.docker.auto_importtoadd/update/sync. Muximux then imports, with no modal and no click, every container that carries at least onemuximux.*label (amuximux.discovery.idalone is enough) and does not carrymuximux.app.enabled=false. With explicit opt-in on, the container also needsmuximux.app.enabled=true. Muximux also skips a container that has no usable URL or whose labels give an invalid entry (see Why a container is skipped). Unlabelled containers are never auto-imported.addimports each new labeled container once.updatealso re-syncs an imported app when its labels change.syncalso removes an imported app when its container disappears or opts out. Auto-import does not take over an app that you imported by hand. It leaves that app as it is, andsyncdoes not remove it. Off by default. See Automatic Import. - Detach / Re-link: per-row controls in Settings → Discovery. Detach stops auto-managing an entry. Re-link points it at a different container when you migrate daemons.
Upgrading from 3.5 or earlier? Read Upgrading to 3.6 first.
✅ You run apps as Docker containers on the same host as Muximux (or on hosts Muximux can reach over the Docker API) ✅ Container IPs change across restarts (default Docker bridge networking) and you don't want to chase them by hand ✅ You're comfortable granting Muximux read access to the Docker socket
❌ Your apps don't run in Docker (the scanner has nothing to list) ❌ Your containers always have stable IPs / hostnames (manual app entries are simpler) ❌ You can't or don't want to expose the Docker socket to Muximux (this feature is opt-in; everything else works without it)
-
Open Settings → Discovery.
-
Tick Enable Docker discovery.
-
Pick a Network strategy.
-
Click Test connection.
The banner turns green when Muximux can reach the daemon and can identify enough about itself to use the chosen strategy.
-
Click Save. The test does not save the settings.
-
Open the Apps tab (or the Gateway tab).
-
Click Discover from Docker.
The modal lists every running container that the daemon returned. Muximux leaves out its own container, so you can't import yourself as an app by accident. Each row shows:
- Suggested name, icon, group. For images in the catalog (Muximux's built-in list of known apps), Muximux fills these in at "medium" confidence.
- Stable tracking key, the ID that Muximux uses to follow the container (operator label > Swarm service > Compose service > container name > container ID)
- Resolved URL preview
- Stability warning when the key is likely to break on a
docker-compose --force-recreateor swarm task reschedule - A Not importable chip when auto-import would skip the container, with the reason (see Why a container is skipped)
The catalog matcher accepts the prefixes that operators often add to names. A container named
homelab-sonarr,homelab_radarr, orprod.plexstill picks up the matching catalog entry, just like a baresonarr/radarr/plexwould. The matcher splits names into tokens at-,_, and.. It compares whole tokens only, sotransmissionicdoes not matchtransmission. Multi-word app names likehome-assistantmatch through a fallback that compares adjacent pairs of tokens.A container that is already tracked shows a Tracked chip in the Discover dialog. The chip names what tracks it: an app, an auto-imported app, a gateway site or a quarantined entry, plus the endpoint when it differs. You cannot select its row, because you cannot import it again. A row whose name another app already uses shows "Name already in use by another app".
-
Pick the routing mode for each row:
-
Direct - menu links to
http://<container-ip>:<port>directly -
Proxy - menu links via Muximux's
/proxy/<slug>path-prefix reverse proxy (a server that forwards requests to another server, here under a path on the Muximux address) -
Gateway domain - menu links to
https://<your-subdomain>; you must also create the gateway site in the same row
-
Direct - menu links to
-
Click Import.
If a row's group does not exist yet, the import creates it in the same save (see Groups are created automatically).
-
Open Settings → Discovery → Currently tracked.
Every imported app or gateway site appears here. Detach on a row stops auto-management. Re-link appears when the saved DockerEndpoint no longer matches the configured endpoint (typical after a daemon migration). A row shows "Container missing since " while Muximux cannot find its container on the daemon. Invalid Docker-owned entries that Muximux did not load are listed below the table; see Quarantined entries.
discovery:
docker:
enabled: true
endpoint: unix:///var/run/docker.sock # or tcp://host:2376
tls: # only needed for tcp:// with mTLS
enabled: false
ca_cert: "" # path to CA bundle that signed the daemon cert
client_cert: "" # path to client cert (PEM)
client_key: "" # path to client key (PEM, chmod 600)
network_strategy: container_ip # see "Strategies" below
network_filter: "" # optional: scope scans to one network
host_ip: "" # required by host_port strategy
refresh_interval: 60s # poller cadence, [10s, 1h]
auto_import: off # off (default) | add | update | sync (3.2.0)
require_explicit_enable: false # only containers with muximux.app.enabled=true (3.6.0)
lifecycle_enabled: false # allow start/stop/restart of tracked containers (needs a daemon that accepts writes)
lifecycle_min_role: admin # min role for lifecycle controls
lifecycle_allowed_groups: [] # additionally require group membership
health_badge_placement: overview # overview | overview_and_nav | offHow you grant Muximux access to the Docker daemon depends on how you run Muximux. If you leave the endpoint: field in config.yaml blank, Muximux fills in the platform default. So most operators only need the OS-level access step below.
services:
muximux:
image: ghcr.io/mescon/muximux:latest
# ... usual ports / volumes / env ...
volumes:
- ./data:/app/data
# :ro does not limit Docker API calls; see "Container lifecycle
# controls" below for what actually gates start/stop/restart.
- /var/run/docker.sock:/var/run/docker.sock:roThat is all you need. At startup, the entrypoint (the script that starts Muximux in the container) checks the bind-mounted socket and reads its group ownership from the host. It then adds the runtime user to a matching group inside the container. This lets the non-root muximux process read the socket. You do not need a DOCKER_GID env var or group_add, or to look up the right group number. The default endpoint: unix:///var/run/docker.sock already matches the mount.
The trailing :ro only stops the container from replacing or deleting the socket file. It does not limit what can be sent through the socket. Anything that can connect to the socket can use the whole Docker API, including to create privileged containers. Treat socket access as root on the host, whatever the mount flag. Gate the dashboard with auth. To narrow what Muximux can do, put a socket proxy (a small service that filters Docker API calls) in front of the socket. Then point endpoint at the proxy. Filter by endpoint, not only by HTTP method. A GET can attach to a running container's console through a WebSocket. A broad POST allowance for containers also allows creating them. Expose only what Muximux needs: listing and inspecting containers, plus services and tasks on Swarm. Add the start, stop and restart endpoints only if you use lifecycle controls. Keep the proxy itself reachable only by Muximux.
Container lifecycle controls (start / stop / restart, see below) are opt-in through two layers. The daemon must accept write requests, and discovery.docker.lifecycle_enabled: true must be set. When Muximux connects to the daemon, it sends a harmless POST to check the first layer. A plain socket mount passes this check, :ro or not. A socket proxy that blocks POST fails it. Neither layer alone is enough: the dashboard still won't start, stop, or restart anything until both are in place. Even with both on, Muximux can only start, stop, and restart the containers it already tracks. It can't pull or build images, create or delete containers, run commands inside them, or touch networks and volumes (Muximux never calls those parts of the Docker API). Muximux writes every action, and every blocked attempt, to the audit log.
For rootless Docker, docker-socket-proxy sidecars, or custom socket paths, you can set two override env vars: DOCKER_SOCKET (the socket path that the entrypoint checks) and DOCKER_GID (skips auto-detection and forces a specific GID). Almost no one needs these.
In this setup there is no container, so there is no entrypoint script. Linux's normal socket permissions apply. The OS user that runs the binary must be a member of the host's docker group.
# Add the user that runs Muximux to the docker group:
sudo usermod -aG docker $(whoami)
# Then re-login (or restart the muximux service) so the new
# group membership takes effect.If you install Muximux as a systemd unit, you can also set the group directly in the unit:
[Service]
User=muximux
SupplementaryGroups=docker
ExecStart=/usr/local/bin/muximux --data /var/lib/muximuxThe default endpoint: unix:///var/run/docker.sock works as is.
Docker Desktop on macOS creates a host-side socket symlink at /var/run/docker.sock. So the default endpoint: unix:///var/run/docker.sock works out of the box for most setups.
If you've disabled Docker Desktop → Settings → Advanced → "Allow the default Docker socket to be used", Docker Desktop does not create the symlink. Either re-enable that toggle, or point endpoint: at the per-user socket that Docker Desktop still maintains:
discovery:
docker:
endpoint: unix:///Users/<your-user>/.docker/run/docker.sockDocker on Windows exposes a named pipe (a Windows channel between programs) rather than a unix socket. Muximux 3.1.0+ supports the npipe:// scheme natively. It uses that scheme by default when it runs on Windows, so you need no extra config:
discovery:
docker:
enabled: true
# endpoint is auto-filled to npipe:////./pipe/docker_engine on WindowsThe Windows account that runs Muximux only needs to be a member of the docker-users group.
For a Docker daemon on a different host:
discovery:
docker:
enabled: true
endpoint: tcp://docker-host.lan:2376
tls:
enabled: true
ca_cert: /etc/muximux/docker-ca.pem
client_cert: /etc/muximux/docker-cert.pem
client_key: /etc/muximux/docker-key.pemThe remote daemon must expose its API with TLS (dockerd --tlsverify). The Muximux process must be able to read the cert/key paths.
| Strategy | URL shape | Requires |
|---|---|---|
container_ip |
http://<docker-network-ip>:<port> |
Muximux runs in a container on the same docker network, or network_filter is set |
container_dns |
http://<container-name>:<port> |
Same prerequisites as container_ip; Docker's internal DNS resolves names within a network |
host_port |
http://<host_ip>:<published-port> |
Container has -p <host>:<container> published; host_ip is set in config |
host_docker_internal |
http://host.docker.internal:<published-port> |
Muximux runs in a Docker Desktop / WSL container where host.docker.internal resolves |
Strategy gating: when Muximux runs natively (not in a container), it cannot identify its own container. So container_ip and container_dns need a network_filter instead. The banner above the form tells you whether the chosen strategy is workable in your environment.
network_filter applies everywhere Muximux reads containers. The scan and the background refresh list the same filtered set and see the same networks. A container attached to several networks gets its URL from the filtered network only, so a refresh never rewrites it to an address on another network. A tracked container that is not on the filtered network counts as missing. On Swarm, the /services endpoint is read once per refresh tick.
Label any container with muximux.* keys, and the Discover modal picks them up as high-confidence pre-fills (values filled in for you). After docker compose up, a fully-labelled container becomes a fully-configured Muximux entry with a single click in the Discover modal. You need no editing after the import. If you turn on automatic import, you need no click at all. This is the "GitOps your apps" pattern: declare your dashboard intent in docker-compose.yml alongside the service it describes.
Full example, showing one of each kind:
services:
sonarr:
image: linuxserver/sonarr
labels:
# ── Tracking ─────────────────────────────────────────────
- muximux.discovery.id=sonarr-stable
# ── App fields (menu entry) ──────────────────────────────
- muximux.app.enabled=true
- muximux.app.name=Sonarr
- muximux.app.icon=sonarr
- muximux.app.group=Media
- muximux.app.port=8989
- muximux.app.scheme=https
- muximux.app.path=/
- muximux.app.health=/api/v3/health
- muximux.app.color=#3498db
- muximux.app.order=10
- muximux.app.default=false
- muximux.app.open_mode=iframe
- muximux.app.proxy=true
- muximux.app.proxy_skip_tls_verify=true
- muximux.app.min_role=user
- muximux.app.allowed_groups=family,admins
- muximux.app.permissions=clipboard-read,clipboard-write
- muximux.app.allow_notifications=true
- muximux.app.allow_navigation=true
- muximux.app.shortcut=1
# ── Gateway routing (subdomain + auth gate) ──────────────
- muximux.app.gateway.domain=sonarr.example.com
- muximux.gateway.tls=auto
- muximux.gateway.streaming=false
- muximux.gateway.strip_frame_blockers=true
- muximux.gateway.forwarded_headers=true
- muximux.gateway.require_auth=true
- muximux.gateway.min_role=user
- muximux.gateway.allowed_groups=family,adminsThe example above sets every label at once. In practice you set only the few an app needs. With automatic import (3.2.0+), these labels are the whole configuration. Here is what each common case looks like on its own. Every block is a complete, copy-pasteable services: entry.
A catalog app, the short way. If the image is one Muximux recognises, a single tracking label is enough. The name, icon, group, port, and health come from the catalog:
services:
sonarr:
image: linuxserver/sonarr
labels:
- muximux.discovery.id=sonarrAn app Muximux does not know. For an image outside the catalog, opt in with enabled and supply the basics:
services:
myapp:
image: ghcr.io/me/myapp
labels:
- muximux.discovery.id=myapp
- muximux.app.enabled=true
- muximux.app.name=My App
- muximux.app.icon=myapp
- muximux.app.group=Tools
- muximux.app.port=8080An app that refuses to embed. Route it through the built-in reverse proxy so it loads in an iframe:
services:
radarr:
image: linuxserver/radarr
labels:
- muximux.discovery.id=radarr
- muximux.app.port=7878
- muximux.app.proxy=truePublished on its own subdomain. Add gateway labels and Muximux serves the app at a public HTTPS address (automatic TLS) behind the login:
services:
grafana:
image: grafana/grafana
labels:
- muximux.discovery.id=grafana
- muximux.app.name=Grafana
- muximux.app.port=3000
- muximux.app.gateway.domain=grafana.example.com
- muximux.gateway.tls=auto
- muximux.gateway.require_auth=trueA button that fires a request, not a page. Use http_action to turn a tile into a webhook trigger (for example an n8n flow), with a confirmation prompt. Muximux sends the request to the app URL, which it builds from port + path:
services:
n8n:
image: n8nio/n8n
labels:
- muximux.discovery.id=nightly-backup
- muximux.app.name=Run Backup
- muximux.app.icon=n8n
- muximux.app.port=5678
- muximux.app.path=/webhook/backup
- muximux.app.open_mode=http_action
- muximux.app.http_action_method=POST
- muximux.app.http_action_confirm=trueRestricted to certain people. Gate an app by role and group:
services:
portainer:
image: portainer/portainer-ce
labels:
- muximux.discovery.id=portainer
- muximux.app.port=9000
- muximux.app.proxy=true
- muximux.app.min_role=admin
- muximux.app.allowed_groups=opsYour apps already have public names behind Traefik, Authentik, NPM or another proxy, and Muximux should open those names rather than container IPs:
services:
sonarr:
image: lscr.io/linuxserver/sonarr
labels:
- muximux.app.name=Sonarr
- muximux.app.group=Media
- muximux.app.icon=sonarr
- muximux.app.port=8989
- muximux.app.url=https://sonarr.example.com
- muximux.app.health=/pingSonarr opens at https://sonarr.example.com. The health check calls http://<container IP>:8989/ping. When the container's IP changes, the poller updates that address and logs "Docker health address refreshed". The poller never rewrites the app URL. Muximux resolves a relative health label against the container. It keeps an absolute URL label as written and never rewrites it. Without a health label, the check goes to the container's URL, including muximux.app.path. Enable monitoring with muximux.app.health_check=true or in the app's settings.
The poller owns the health address of such an app. It rewrites health_url on every refresh, so it overwrites an edit made in Settings. To pin the address, set muximux.app.health to an absolute URL. Muximux keeps that URL as written.
If you remove muximux.app.url later, the app returns to its container URL on the next refresh tick. Editing the URL by hand in Settings detaches the app, as with any tracked app. Known limitation: after you remove the muximux.app.url label, an app imported manually keeps the container address it had as its health address. Set it in the app's settings if needed. For auto-imported apps, auto-import resets it.
muximux.app.icon and muximux.group.icon take the same values:
| Value | Icon | Example |
|---|---|---|
<slug> |
Dashboard Icons slug (the original form) | sonarr |
dashboard:<slug> |
Dashboard Icons slug, explicit | dashboard:sonarr |
lucide:<name> |
Lucide icon | lucide:shield-check |
https://... |
Icon image at that URL (https only) | https://example.com/icons/media.svg |
url:<url> |
Icon image at that URL, explicit | url:https://example.com/icons/media.svg |
labels:
- muximux.app.icon=lucide:database
- muximux.group.icon=https://example.com/icons/media.svg- A bare value is always a Dashboard Icons slug. Muximux never guesses Lucide from a bare name, because names such as
serverexist in both sets. Writelucide:serverinstead. A bare value containing:,/,\,?,#or whitespace is not a slug. Since 3.6.1, Muximux ignores it. Use thedashboard:,lucide:or URL form. - Prefixes are case-insensitive. Slugs and Lucide names are lowercased; URLs are kept exactly as written (paths and queries are case-sensitive).
- A Lucide name is lowercase letters, digits and dashes. Muximux checks that format only, so a name Lucide does not have shows as a missing icon, as in the UI.
- A URL must be an absolute
httpsURL with a host, no credentials or spaces, and at most 2048 characters. Muximux's Content-Security-Policy (the rules that tell the browser what it may load) only allows images over https. So Muximux refuseshttpURLs and other schemes such asjavascript:,data:andfile:. The browser loads a URL icon straight from that address, and Muximux does not proxy or cache it. So the host must be reachable from the browser. - Muximux ignores an invalid value. The scan notes it, and Muximux logs one warning each time the value changes. The stored icon is kept, and discovery carries on.
- A label cannot name a custom upload.
A bare muximux.app.icon value is a Dashboard Icons slug: the icon filename without its extension (sonarr.svg becomes sonarr). The label flow has no GUI in front of you, so here is where to look one up:
- Browse the gallery at dashboardicons.com and search for your app.
- Or search visually in Muximux's own app editor (Add or Edit an app, then the icon picker). The name you land on is the slug to paste into the label.
- Or list them straight from your running instance:
GET /api/icons/dashboardreturns every available slug (it is the same data the picker uses).
Omit the label to fall back to the catalog icon. For Lucide icons, see Lucide or the Lucide tab of the icon picker.
How values are read:
-
Booleans are true for
true,1,yesoronand false forfalse,0,nooroff(case-insensitive, surrounding spaces ignored). Muximux ignores any other value, including an empty one, and reports it in the Discover modal. This applies to every boolean label (enabled,default,proxy,proxy_skip_tls_verify,allow_notifications,allow_navigation,allow_deep_links,health_check,http_action_confirm,http_action_show_toastand themuximux.gateway.*ones). So a misspeltmuximux.app.enabled=trudoes not opt the container out. On update and sync, a misspelt or empty value keeps the app or gateway site's current setting. So a typo or an undefined template variable inmuximux.gateway.require_authnever makes a protected site public. On first import, the default applies. -
Invalid values for other typed labels (a port outside 1-65535, an unknown
open_mode, a colour that is not a hex colour, and so on) are ignored, as if the label were not set. Muximux lists each ignored value in the Discover modal's notes for the container. It logs a warning once for each value, until the value changes. -
Labels that are set win while an app is tracked. On apps you imported by hand, Muximux re-syncs
muximux.app.name,icon,groupandorderon every refresh, whatever theauto_importmode. Underupdate/sync, Muximux re-syncs auto-imported apps from all their labels. Underoffandadd, it leaves them alone. Themuximux.group.*labels apply to groups that Docker discovery created. A label that is not set never changes anything. To take a field back, remove the label or Detach the app. See Label re-sync for tracked apps and Group labels. - Unknown
muximux.*labels are listed in the Discover modal's notes for the container.
| Label | Type | Default | What it does |
|---|---|---|---|
muximux.discovery.id |
string | (container name) | Stable tracking key that survives docker-compose --force-recreate and swarm reschedules. Most important label for plain containers - without it, Muximux falls back to the Swarm service, the Compose service, then the container name (see Tracking keys). Swarm tasks and Compose services stay stable without it. |
| Label | Type | Default | What it does |
|---|---|---|---|
muximux.app.enabled |
bool | true |
Opt-out via false. With require_explicit_enable (or MUXIMUX_DISCOVERY_REQUIRE_EXPLICIT_ENABLE) only true opts in. See Explicit opt-in. |
muximux.app.name |
string | catalog name or container name | Display name in the menu. Surrounding spaces are ignored. Re-synced while the app is tracked; see Label re-sync for tracked apps. |
muximux.app.icon |
string | catalog icon or ""
|
A Dashboard Icons slug (e.g. sonarr), lucide:<name>, or an https URL; see Icon label formats. Surrounding spaces are ignored. |
muximux.app.group |
string | catalog group | Group the app lives in. Created if it doesn't exist (from 3.6.0). |
muximux.app.port |
int 1-65535 | catalog port or first exposed | Which container port the app listens on. |
muximux.app.url |
absolute http(s) URL |
unset | Open the app at this URL instead of the container address, e.g. its public name behind your own reverse proxy. Health checks still go to the container. Ignored (with a scan note) when muximux.app.gateway.domain is set, and invalid values are ignored with a note. See Running behind your own reverse proxy. |
muximux.app.scheme |
http | https
|
http |
Scheme for the constructed URL. |
muximux.app.path |
string | / |
Sub-path appended to the container URL (e.g. /admin). Not applied to muximux.app.url or to a gateway site's backend. |
muximux.app.health |
string | catalog default | Health-check address: a full URL, or a path such as /api/v3/health resolved against the container. A value starting with // or /\ is not a path and is ignored (since 3.6.1). |
muximux.app.health_check |
bool | unset | Enables (true) or disables (false) health monitoring for the app; the endpoint still comes from muximux.app.health. Unset keeps the setting in the app's form. Docker-managed: re-synced on update/sync and shown locked in Settings. |
muximux.app.color |
hex colour | unset | Accent color in the dashboard: #rgb, #rgba, #rrggbb or #rrggbbaa. |
muximux.app.order |
int 0-9999 | unset | Sort order within the group. |
muximux.app.default |
bool | false |
Load this app automatically when the dashboard opens. |
muximux.app.open_mode |
iframe | new_tab | new_window | redirect | http_action
|
iframe |
How clicking the menu entry opens the app. http_action fires an HTTP request instead of opening a page. |
muximux.app.http_action_method |
GET | POST | PUT | DELETE | PATCH
|
POST |
With open_mode=http_action, the HTTP method to send to the app URL. |
muximux.app.http_action_headers |
csv Key=Value
|
unset | Extra request headers, comma-separated (e.g. Authorization=Bearer xyz). |
muximux.app.http_action_confirm |
bool | false |
Show a confirmation prompt before firing. |
muximux.app.http_action_show_toast |
bool | true |
Show a result toast after firing. |
muximux.app.proxy |
bool | false |
Route through Muximux's built-in reverse proxy (strips iframe-blocking headers, rewrites paths). Required for many apps that refuse to embed. |
muximux.app.proxy_skip_tls_verify |
bool | true |
When proxy=true, skip backend TLS cert verification (useful for self-signed homelab apps). |
muximux.app.min_role |
user | power-user | admin
|
unset | Minimum role required to see this app. Admins always bypass. |
muximux.app.allowed_groups |
csv | unset | Comma-separated group allow-list; user must belong to at least one. Case-insensitive. Stacks with min_role. |
muximux.app.permissions |
csv | unset | Iframe feature delegations (camera, microphone, geolocation, clipboard-read, clipboard-write, fullscreen, ...). |
muximux.app.allow_notifications |
bool | false |
Enable the cross-iframe Notifications API bridge for this app. |
muximux.app.allow_navigation |
bool | false |
Let this app switch Muximux to another app (and open a page inside it) through target="_top" links and a postMessage API. A _top link can also send the whole tab to any website after a click, and a visible app can switch apps without a click, so enable it only for apps you trust. See Navigation from Embedded Apps. |
muximux.app.allow_deep_links |
bool | false |
Let a Muximux link such as #emby?path=... open a page inside this app. Anyone who can send you a link can then open any page of the app, so leave it off for apps that change something when a page is opened. See Deep links in links. |
muximux.app.shortcut |
int 1-9 | unset | Keyboard shortcut slot. |
muximux.app.gateway.domain |
string | unset | Required for auto-import to create a gateway site; the derived <name>.<dashboard domain> default only pre-fills the import modal. When set, the import modal also offers a gateway-site entry for this subdomain. Pairs with the muximux.gateway.* labels below. |
These describe the group the container's app is in. They apply only to a group Docker discovery created; see Group labels.
| Label | Type | Default | What it does |
|---|---|---|---|
muximux.group.icon |
string | folder icon | The same forms as muximux.app.icon (slug, lucide:<name>, https URL). Surrounding spaces are ignored. |
muximux.group.color |
#rrggbb |
unset | Group colour, a hex colour (#rgb, #rgba, #rrggbb or #rrggbbaa). Other values are ignored with a warning and a scan note. |
muximux.group.order |
int 0-9999 | after existing groups | Sort order of the group. Other values are ignored with a warning and a scan note. |
| Label | Type | Default | What it does |
|---|---|---|---|
muximux.gateway.tls |
auto | none | custom
|
auto |
TLS handling for the subdomain. auto runs Let's Encrypt; none is plain HTTP; custom expects tls_cert and tls_key paths (set those manually in the import modal). |
muximux.gateway.streaming |
bool | false |
Disable Caddy response buffering for live-streaming backends. |
muximux.gateway.strip_frame_blockers |
bool | true |
Drop X-Frame-Options / Content-Security-Policy: frame-ancestors on responses so the site can be iframed elsewhere. |
muximux.gateway.forwarded_headers |
bool | true |
Forward X-Forwarded-Proto / X-Forwarded-Host / X-Real-IP. Turn off only when your backend has its own handling. |
muximux.gateway.skip_tls_verify |
bool | false |
Skip verification of the backend's TLS certificate. Only takes effect when the backend URL is https -- use it for self-signed / untrusted backends like Proxmox on :8006. Leaves the public-facing certificate unaffected. |
muximux.gateway.require_auth |
bool | false |
Gate the subdomain behind Muximux's login. Visitors land on /login first; admins bypass per-site role / group rules. Requires server.session_cookie_domain to be set. |
muximux.gateway.min_role |
user | power-user | admin
|
unset | When require_auth=true, minimum role to access the site. |
muximux.gateway.allowed_groups |
csv | unset | When require_auth=true, allow-list groups (comma-separated, case-insensitive). |
Unknown muximux.* labels are surfaced in the Discover modal's per-row notes, so a typo shows up instead of being silently ignored.
Everything above is the manual path. Labels become high-confidence pre-fills, and you click Import to commit them. Automatic import removes that review step. When it is on, Muximux imports by itself every container that carries at least one muximux.* label (and is not opted out). Muximux skips containers that fail the conditions in Explicit opt-in and Why a container is skipped. There is no modal and no click. Under update and sync, Muximux also keeps the imported apps in step with the labels over time.
Security -- read before enabling. Auto-import is off by default. Only the host operator (who controls
config.yamlor the environment) can turn it on. Once it is on, any container on the shared Docker socket can write itself into your config with no review step. This includes amuximux.app.gateway.domainlabel, which publishes a public HTTPS subdomain with an auto-issued ACME certificate (a TLS certificate that is issued automatically). Treat enabling this as trusting every label on every container the daemon can see. If you don't control all of those containers, leave itoffand import by hand.
Set the mode with the discovery.docker.auto_import config key, or override it with the MUXIMUX_DISCOVERY_AUTO_IMPORT environment variable (the env var wins). Four values:
| Mode | Adds new labelled containers (at least one muximux.* label, not opted out) |
Re-syncs app fields when labels change | Removes the app when the container disappears or opts out |
|---|---|---|---|
off (default) |
no -- labels stay suggestions you import by hand | no | no |
add |
yes, once | no -- imported, then left alone forever | no |
update |
yes | yes | no |
sync |
yes | yes | yes -- full GitOps mirror |
-
off-- today's behavior. Labeled containers are suggestions only. Muximux writes nothing until you click Import. -
add-- a newly labeled container is imported one time, then never touched again. Good for bootstrapping. -
update-- likeadd, plus Muximux re-syncs the app's fields from the labels whenever they change. Never removes anything. -
sync-- likeupdate, plus Muximux removes the auto-imported app (and its gateway site) when its tracked container disappears from the daemon or opts out withmuximux.app.enabled=false. Removal waits until the container has been absent for three consecutive successful scans, so a restart does not remove and re-create the app. Only auto-imported apps are removed. Muximux never touches apps you imported by hand or detached. The config becomes an exact mirror of the labelled containers.
discovery:
docker:
enabled: true
auto_import: sync # off (default) | add | update | sync# Environment override (takes precedence over config.yaml):
MUXIMUX_DISCOVERY_AUTO_IMPORT=syncThe override applies in memory only and is never written to config.yaml. Settings -> Discovery shows the field as locked ("From MUXIMUX_DISCOVERY_AUTO_IMPORT"). The Discovery tab shows the stored values (host IP, network filter, refresh interval, auto-import mode, badge placement). When you save the tab, Muximux merges it onto the stored config, so fields that the tab does not show are kept. On Windows, npipe:// endpoints can be entered in Settings.
Auto-import skips a container with muximux.app.enabled=false, and the Discover modal hides it. Use it to keep a labelled container off the dashboard without stripping its labels. Under sync, Muximux removes an app already auto-imported from that container, and its gateway site, after the grace period. Under update, Muximux leaves the app alone.
By default, every labelled container that is not opted out is imported. To require a positive label per container, set discovery.docker.require_explicit_enable: true (or MUXIMUX_DISCOVERY_REQUIRE_EXPLICIT_ENABLE=true, which wins and applies in memory only; Settings shows the field as locked). Then Muximux imports only containers with muximux.app.enabled=true. It skips labelled containers without it as not_enabled. Muximux ignores invalid values of the environment variable and logs a warning. (#496)
A container with no usable URL is never imported. The Discover modal shows a Not importable chip with the reason, and GET /api/discovery/docker/scan returns it as auto_import_skip:
| Code | Meaning |
|---|---|
unlabeled |
No muximux.* label on the container. |
disabled |
muximux.app.enabled=false. |
not_enabled |
Explicit opt-in is on and muximux.app.enabled=true is missing. |
no_port |
No port could be determined; add muximux.app.port. |
no_url |
No URL could be built with the current network strategy. |
invalid |
The labels produce an invalid entry; the detail says why. |
When a container loses all its muximux.* labels, Muximux detaches its auto-imported app from auto-import. The app is kept, its URL is still refreshed, and sync never removes it. The app is still tracked, so the label re-sync applies to it if labels come back. The same happens in two other cases. On upgrade, it happens to an auto-imported app whose container has no labels. When you turn on explicit opt-in, it happens for containers without enabled=true.
Auto-import never silently overwrites a URL that you took manual control of. Changing an auto-imported app's URL detaches that app from auto-management. This applies to a change in Settings, through the API, or in config.yaml directly. Removing the container's muximux.* labels also detaches it from auto-import (see above). From then on it is a normal manual entry: update/sync will not re-sync it from labels, and sync will not remove it. This is the same edit-lock / auto-detach mechanism described below for tracked URLs.
Other managed-field edits (name, icon, group, and similar) do not detach. The same applies to the health check. When muximux.app.health_check is set, Muximux records a server-owned docker_managed_health_check marker on the app. It re-syncs the value under update/sync, and the app form shows the toggle locked. Remove the label to unlock it. Under update/sync, Muximux re-syncs those edited fields from the labels on the next tick, so the labels remain the source of truth. Under add, the edits stick, because add never re-syncs an already-imported app.
While an app is tracked, labels that are set win; detach to take control.
This holds for every tracked app, including apps you imported by hand through the Discover dialog. It also works with auto_import: off. On each refresh tick, Muximux checks every tracked app whose container is present. It applies these labels when they are set on the container:
| Label | Applied as |
|---|---|
muximux.app.name |
The app name. A gateway site linked to the app follows the rename. |
muximux.app.icon |
The icon, as on import (dashboard, Lucide or URL; see Icon label formats). Icon colour, background, variant and invert are kept. |
muximux.app.group |
The group, matched to an existing group by name, ignoring case and spacing (infra finds Infra). Created if no group matches. |
muximux.app.order |
The order within the group. |
The URL and health address keep following the container as before.
- A label that is not set never changes anything: your own name, icon, group or order stays.
- If you change one of these fields in Settings while the label is set, the next tick sets it back. To take control, remove the label or Detach the app (Settings -> Discovery -> Currently tracked). Muximux never touches an app you detached (Detach in Settings), or an untracked app you created yourself in Settings.
- The re-sync only updates apps that are already tracked. It never imports a container or removes an app, whatever the
auto_importmode. - Auto-imported apps follow their
auto_importmode instead (re-synced underupdate/sync, left alone underoffandadd), so no field is written twice. - If you rename a group in Settings while a container's
muximux.app.grouplabel still names the old group, the label re-creates the old group on the next tick. Change the label too. - When Muximux cannot apply a label, it holds the label back and logs a warning once. This happens when the name is already used by another app, or when the name is over 100 characters. Muximux compares names like proxy paths, so
TVandtvcollide. The app keeps its current value until the conflict is resolved. - If saving the config fails, Muximux rolls back the whole tick and retries on the next tick.
When an app lands in a group that does not exist, Muximux creates the group in the same save. This covers a manual import from the Discover dialog, auto-import (new apps and re-synced ones) and the label re-sync above. It applies to a group from a muximux.app.group label as well as a catalog group.
- Muximux matches an existing group by name first, then ignoring case and spacing. So
media,Mediaandmedia-server/Media Servernever create a near-duplicate. Muximux stores the app with the existing group's exact name. - A new group gets the same defaults as one added in Settings: a folder icon, no colour, expanded. Muximux places it after your existing groups, in the order it processed the apps. Customise it in Settings like any other group.
- If you delete a group while a tracked app has
muximux.app.groupset to it, Muximux creates the group again on the next tick. Remove the label or detach the app to stop that. - If the save fails, Muximux rolls back the new groups together with the apps.
- Muximux never hides an app whose group is missing anyway (for example a group removed from
config.yamlby hand). The navigation and Settings -> Apps list it under Ungrouped until the group exists again.
muximux.group.icon, muximux.group.color and muximux.group.order set the look and position of the group a container's app is in. Put them on any container whose app is in the group. They need no muximux.app.group on the same container. But without a group there is nothing to apply them to, and the Discover dialog notes that.
services:
sonarr:
labels:
- muximux.app.group=Media
- muximux.group.icon=plex
- muximux.group.color=#e5a00d
- muximux.group.order=1-
Only groups Docker discovery created. Muximux marks a group made by an import, auto-import or the label re-sync as Docker-managed (
docker_managed: trueinconfig.yaml). It applies the labels when it creates the group, and re-syncs them on every tick while the group stays managed. Muximux never touches a group you created yourself. -
Edit in Settings to take control. Changing the icon or colour of a managed group in Settings clears the marker. Changing its order (including dragging groups into a new order) clears the marker only when the order comes from a
muximux.group.orderlabel. If no label sets the order of a managed group, you can reorder it freely and it stays managed. Once the marker is cleared, the group is yours, and Muximux ignores later label changes. Renaming or expanding/collapsing the group does not count. To hand a group back to the labels, setdocker_managed: trueinconfig.yaml. - A label that is not set never changes anything: the group keeps its own value for that field.
- Conflicts. When several containers in one group set different values, the container with the lowest tracking key wins, per field. The others get a scan note in the Discover dialog and a warning in the log (once until the conflict changes).
- Invalid values (a colour that is not a hex colour, an order outside 0-9999) are ignored. Muximux logs one warning per change and adds a scan note.
- Muximux reads the labels from the containers of tracked apps and of tracked gateway sites (through the site's linked app), whatever the
auto_importmode. A group created by a manual import gets its label values on the next refresh tick. - Applying them is part of the tick's single save. If the save fails, Muximux rolls back the group changes together with everything else.
In update and sync, re-sync compares both the app fields and the gateway site built from labels against what is stored. Two kinds of gateway labels propagate on the next tick. The first kind changes the app's URL: muximux.app.gateway.domain and muximux.gateway.tls. The second kind is gateway-only labels that do not map to any app field: muximux.gateway.require_auth, muximux.gateway.min_role, muximux.gateway.allowed_groups, muximux.gateway.streaming, muximux.gateway.strip_frame_blockers, muximux.gateway.forwarded_headers, and muximux.gateway.skip_tls_verify. For example, if you toggle muximux.gateway.require_auth on a running container, Muximux re-syncs it without any app-field change.
Only the explicit muximux.app.gateway.domain label makes auto-import create a gateway site. With server.tls.domain set, the derived <name>.<dashboard domain> default is only a pre-fill in the import dialog. An update changes only label-managed fields. It keeps the health check, auth bypass, access, scale, pinned, proxy headers and other per-app settings.
Upgrade note: when server.tls.domain was set, earlier versions created a gateway site <name>.<your domain> for every labelled container. If you relied on those derived subdomains, add muximux.app.gateway.domain=<name>.<your domain> to those containers before upgrading. Otherwise, the first refresh removes the sites and points the apps at their container URLs.
If you remove the muximux.app.gateway.domain label from an already-imported container, the next tick acts on it. Muximux returns the app to the direct container URL and drops the gateway site, which no label declares any more.
Swarm services and Compose projects are tracked by name, so redeploys and --force-recreate do not create duplicates.
The key is the first of these that applies:
| Order | Source | Key |
|---|---|---|
| 1 |
muximux.discovery.id label |
label:<value> |
| 2 | Swarm service | swarm:<service> |
| 3 | Compose project and service | compose:<project>:<service> |
| 4 | Container name |
name:<name> (shown with a stability warning) |
| 5 | Container ID |
id:<id> (last resort) |
So Swarm tasks and Compose services no longer need muximux.discovery.id for stability. On the first refresh, Muximux migrates existing name: keys to the stable key automatically and logs a Docker tracking key migrated audit line. Entries tracked on another endpoint are migrated after Re-link. Quarantined entries keep their old key. sync removes them once the task is gone from the endpoint it polls, or you can remove them in Settings. sync also cleans up duplicates left by earlier redeploys.
There is one app per key. Muximux collapses Swarm replicas and the containers of a scaled Compose service (--scale) into a single app. With container_ip and several replicas, the address may alternate between them.
- Labels under the service's
labels:reach the task.deploy.labelsare service labels, and Muximux reads them too. Container labels win when both set the same key. - Published ports come from the service, so the
host_portandhost_docker_internalstrategies work with ingress-published ports. -
container_dnsuses the service name. - The endpoint must be a manager node, because only managers answer
/services. On a worker, the scan shows a note and the app needsmuximux.app.port. - Behind a socket proxy such as tecnativa/docker-socket-proxy, allow
/serviceswithSERVICES=1. Without it, Muximux logs one warning ("Swarm services unavailable; using task data only") and uses task data only. Service labels and published ports are then missing.
A Docker-owned entry is an auto-imported app, or a gateway site that auto-import created for one. An invalid one fails validation, for example one that an older version wrote without a URL. Such an entry in config.yaml no longer stops Muximux from starting, and it no longer causes a save from Settings to be rejected. Instead, Muximux quarantines the entry. The entry is:
- kept in
config.yaml, unchanged, until it is fixed, removed, or superseded (see below), - not loaded, so it does not appear on the dashboard,
- logged once at startup as "Invalid Docker auto-imported entry quarantined", and
- listed in Settings -> Discovery -> Tracked with its reason.
To clear a quarantined entry, do one of these:
-
Fix the labels. If auto-import is
add,updateorsync, fix the container's labels. The next refresh replaces a quarantined app. A quarantined gateway site of a live app is replaced only underupdateorsync. With auto-importoff, a refresh does not replace the entry. -
Remove it. Click Remove or Remove all in the list. Removing deletes the entry from
config.yaml. A live app or gateway site that shares its tracking key stays tracked.
Muximux also clears a quarantined entry by itself in two cases:
-
A live entry supersedes it. This happens when a live app takes its name or slug, or a live gateway site takes its domain. Muximux then drops the entry from
config.yamlat the next save and logs "Quarantined entry superseded by a live entry". A quarantined site goes with its superseded app. -
The container is gone under
sync. Muximux removes a quarantined app whose container is gone from the polled endpoint after three consecutive scans, like an auto-imported app.
A manual gateway site that was linked to a quarantined app loses its app link. Only Docker-owned entries are quarantined. Other invalid config still fails validation as before.
Other housekeeping applies to discovery. Image names whose last segment is generic (server, app, web, api and similar) no longer match a catalog entry. Muximux deduplicates apps whose names differ only by case or spacing. When a tracked container goes missing, Muximux logs it once instead of on every refresh.
Discovery behaves more predictably from 3.6.0, and a few changes show up on the first refresh after an upgrade:
-
Auto-import needs a label. Only containers with at least one
muximux.*label are auto-imported. Underupdate/sync, the first refresh detaches an auto-imported app from auto-import if its container has no labels. The app stays and its URL keeps refreshing, butsyncno longer removes it. A label that you add later does not put the app back under auto-import. The app stays tracked, so itsname,icon,groupandorderlabels re-sync. Butupdatedoes not apply its other labels, andsyncdoes not remove it. To make it auto-imported again, delete the app. The next refresh then imports the labelled container again, but only if the container meets the conditions in Explicit opt-in and Why a container is skipped. See Containers that lose their labels. -
New tracking keys for Swarm and Compose. Keys become
swarm:<service>andcompose:<project>:<service>. On the first refresh, Muximux migrates existingname:keys in place and logsDocker tracking key migrated. Entries tracked on another endpoint are migrated after Re-link. See Tracking keys. -
Swarm app names. Under
update/sync, Muximux renames an auto-imported Swarm app withoutmuximux.app.namefrom the task name to the service name. This can change its slug and its/proxy/<slug>/path. Behind a socket proxy, allow/services(SERVICES=1). -
Labels re-sync onto apps you imported by hand. A set
muximux.app.name,icon,groupororderlabel now wins on every tracked app, in every mode includingoff. So the next refresh resets an edit to those fields in Settings. Remove the label or Detach the app to keep your edit. See Label re-sync for tracked apps. -
Invalid entries no longer stop startup. An invalid auto-imported app or gateway site in
config.yamlis quarantined (kept in the file, not loaded) with a warning. See Quarantined entries. -
syncremoves less. Only auto-imported apps are removed, and only after the container has been absent for three consecutive scans. -
Catalog matching. Images whose last path segment is generic (
server,app,web,apiand similar) no longer match a catalog entry by that segment, so such a container may needmuximux.app.name,iconandportlabels. -
lifecycle_allowed_groupsholds user and identity-provider group names; renaming or deleting a dashboard group no longer changes it.
From 3.6.1:
- The Docker whale in the navigation and on the overview is shown to admins only, and can be hidden with
navigation.show_docker_badge: false. -
MUXIMUX_DISCOVERY_AUTO_IMPORTandMUXIMUX_DISCOVERY_REQUIRE_EXPLICIT_ENABLEnow also apply on a first start withoutconfig.yaml. A container that relied on them being ignored there will see them take effect. - A
muximux.app.healthvalue starting with//or/\is ignored. - Muximux trims a bare
muximux.app.icon(ormuximux.group.icon) value. It then refuses the value as a Dashboard Icons slug if it still contains:,/,\,?,#, whitespace or control characters. Use thedashboard:,lucide:or URL forms (see Icon label formats).
When you check "Add to menu" in the import modal, a radio selector decides how the menu link works:
Browser → http://192.168.1.4:8989 (your dashboard machine reaches the container directly)
- App.url = the discovered container URL
- App.proxy = false
- The poller refreshes App.url every tick when the container's IP changes
Use when: your dashboard machine has direct network reachability to the container (same host, same subnet, VPN).
Browser → /proxy/sonarr → Muximux Go server → http://192.168.1.4:8989
- App.url = the container URL (kept as the upstream)
- App.proxy = true
- Muximux's built-in path-prefix reverse proxy strips iframe-blockers (headers that stop a page from loading in an iframe), rewrites HTML/CSS/JS paths, isolates
window.parent, etc. This lets apps that refuse to load in iframes work. - Same tracking semantics as Direct (poller refreshes the upstream URL)
Use when: the app misbehaves in iframes, the dashboard machine cannot reach the container directly, or you want auth/CSP layering through Muximux.
Browser → https://sonarr.example.com → Muximux (embedded Caddy, :443, auto-HTTPS) → http://192.168.1.4:8989
Point the subdomain's DNS at the Muximux host. Muximux is the reverse proxy here. Its embedded Caddy listens on ports 80/443 and gets the certificate from Let's Encrypt. Then it proxies the request to the container. You do not put nginx or another proxy in front of it for this to work.
-
App.url =
https://<gateway-domain>(static) - App.proxy = false
- App is NOT auto-managed: the gateway site becomes the docker-managed entry instead
- The poller refreshes the gateway site's
backend_url(not the App's URL, which doesn't depend on the container)
Use when: you want a public subdomain that survives container moves, and a clickable dashboard link that uses that domain.
You may already run an edge proxy (Cloudflare Tunnel, an upstream Traefik/nginx) and would rather it terminate TLS (decrypt the HTTPS traffic). If so, set
server.gateway_listen: ":8443". Then have that proxy forward to Muximux on that port instead. In that case, the flow isBrowser → upstream proxy → muximux:8443 → http://192.168.1.4:8989.
When an App or GatewaySite is tracked, the URL field in the editor is read-only and shows an amber lock badge. Muximux protects your edits across all three ways you might change the URL:
- In Settings, the URL field is locked. To change it, click Detach under Settings → Discovery → Currently tracked. The app's URL unlocks right away in the same Settings session. If you save afterwards, the app stays detached.
- Through the API, if a SaveConfig request changes the URL of a tracked entry, Muximux treats that as a deliberate takeover. It drops the tracking and writes an audit log entry.
-
In
config.yamlby hand, the same thing happens at next boot. Muximux notices that your URL differs from the one the poller last wrote. It drops the tracking and notes it in the log. Your edit survives the next refresh tick.
The sanctioned forget path is the Detach button in Settings → Discovery (or DELETE /api/discovery/docker/track/<key> from a script).
Tracking itself belongs to Muximux, not to the save payload. Muximux ignores docker_key, docker_endpoint, docker_strategy and docker_managed_url in a SaveConfig or per-app PUT, and keeps the stored values. A save can detach an app by changing its URL. But it cannot attach one, re-attach a detached one, or switch it to another container. Only Discover, auto-import and Re-link create or change tracking.
The poller does not rewrite apps with a fixed muximux.app.url. Their docker_managed_url equals the label URL. The poller refreshes their health_url from the container on every tick. So it overwrites a health address edited in Settings, unless muximux.app.health is an absolute URL.
You'll see a docker_managed_url field appear next to docker_key for tracked entries. Muximux writes it from the import flow and updates it on every poller tick. You don't need to touch it. If you do write a tracked entry by hand from scratch, set docker_managed_url to the same value as url (or backend_url for a gateway site). The file-edit detach mechanism then has a baseline to compare against.
Caddy's reload is transactional (all or nothing) only at the parse step. A failure after the parse step (listener collision, async cert provisioning, module panic) can leave the running config in an unknown state. The refresh poller handles this with a rollback (a reload of the previous config):
- The candidate reload fails and the rollback reload succeeds: Muximux logs an audit warning and skips the refresh tick.
- Both reloads fail: the divergence counter goes up, and a sticky red banner appears in Settings → Discovery.
- The first clean tick after a divergence: the banner turns amber and shows "recovered".
The banner shows at a glance that the running Caddy may not match disk. Recovery happens automatically on the next successful tick. The banner stays amber until you acknowledge it (currently by waiting; a future iteration may add a "clear" button).
By default, Caddy listens on 80/443 with auto-HTTPS. This requires root or CAP_NET_BIND_SERVICE. For "behind another proxy" topologies (Traefik, Cloudflare Tunnel, nginx), set server.gateway_listen to a non-privileged port:
server:
listen: ":8080"
gateway_listen: ":8443" # gateway sites served as plain HTTP hereSee TLS and Gateway → Running Behind Another Reverse Proxy for the full topology guide.
To have the dashboard open your proxy's public names instead of container addresses, see Running behind your own reverse proxy.
| Symptom | Diagnosis |
|---|---|
Banner: "Connected to Docker but strategy container_ip cannot identify Muximux's container" |
Muximux runs natively (not in a container). Set network_filter to scope the scan to a known docker network, or switch to host_port. |
| Banner: "Daemon unreachable: dial unix … no such file or directory" | The endpoint path is wrong, or the socket isn't bind-mounted into Muximux's container. |
| Banner: "Daemon unreachable: connect: permission denied" | The socket is mounted but the entrypoint's auto-detection didn't fire (e.g. unusual mount path, docker-socket-proxy sidecar). Override with DOCKER_GID set to the docker group GID the socket is owned by, or DOCKER_SOCKET to point the detection at a non-default path. See Make the daemon socket reachable. |
| Discover modal shows containers but no auto-fill | The image isn't in Muximux's catalog. Add muximux.app.* labels to the container, or fill the fields manually before importing. |
| Imported app's URL doesn't update when container restarts | Check refresh_interval isn't set to 1h. Check the audit log for Docker app URL refreshed (and Docker health address refreshed for health addresses). Check the container hasn't been renamed (breaks name: tracking keys; Swarm and Compose containers use stable keys). |
| Gateway site doesn't serve after import | If you set server.gateway_listen, your upstream proxy needs to forward the host header to that port. Try curl -H 'Host: site.example.com' http://muximux-host:8443/ to bypass the upstream. |
| Discover modal shows "Not importable: No port" | The container exposes no port Muximux can pick. Add muximux.app.port. |
| Container is labelled but not auto-imported | Check the reason in the Discover modal. Common causes: muximux.app.enabled=false, or explicit opt-in is on and muximux.app.enabled=true is missing. Containers with no muximux.* label are never auto-imported. |
| Log says "Invalid Docker auto-imported entry quarantined" | The entry is kept in config.yaml but not loaded. Fix the container's labels (the next refresh replaces it) or remove it under Settings -> Discovery -> Tracked. A manual gateway site linked to it loses its app link. |
| Log says "Swarm services unavailable; using task data only" | The endpoint is not a manager node, or a socket proxy blocks /services. Point Muximux at a manager, or set SERVICES=1 on the proxy. |
| Divergence banner is red and won't clear | Inspect the most recent Docker refresh divergence audit log line for the candidate + rollback errors. Most often a Caddyfile parse-OK but listener-collide situation. Restart Muximux to recover. |
All endpoints are admin-only except GET /api/discovery/docker-state, which returns the container state of the apps the caller can see.
| Method | Path | Body | Description |
|---|---|---|---|
| GET | /api/discovery/docker/status |
- | Capability + cache status |
| GET | /api/discovery/docker/networks |
- | Docker networks, for the network filter |
| GET | /api/discovery/docker/config |
- | The stored discovery settings under config, plus env_overrides for fields set by an environment variable |
| PUT | /api/discovery/docker/config |
DiscoveryDockerConfig |
Merge the fields sent onto the stored discovery settings (omitted fields are kept), save, and rebuild the service |
| POST | /api/discovery/docker/test |
DiscoveryDockerConfig |
Probe a candidate config without saving |
| GET | /api/discovery/docker/scan |
- | Enumerate running containers as Suggestion list, with labeled, label_enabled, auto_import_skip, tracked and name_taken
|
| POST | /api/discovery/docker/import |
{items: ImportItem[]} |
Atomic batch import of selected containers |
| GET | /api/discovery/docker/tracked |
- | Current tracked apps + sites with last-seen and missing_since timestamps, and the quarantined entries |
| DELETE | /api/discovery/docker/track/{key} |
- | Detach tracking for everything matching key on the current endpoint, and delete quarantined entries with that key on any endpoint. ?scope=quarantined deletes only the quarantined entries |
| POST | /api/discovery/docker/relink/probe |
{key} |
"Does this key still resolve on the current daemon?" |
| POST | /api/discovery/docker/relink/confirm |
{old_key, new_key, strategy?} |
Move tracking from old key to new key |
| GET | /api/discovery/docker-state |
- | Container state of tracked apps (any signed-in user; filtered to the apps they can see) |
Field-level details and examples are in the API Reference.
If you want the dashboard to start / stop / restart tracked containers from the overview page:
- Make sure the daemon accepts write requests from Muximux. A plain socket mount already does (
:romakes no difference). If Muximux talks to a socket proxy, allowPOSTto the start, stop and restart endpoints there, and nothing broader. - Set
discovery.docker.lifecycle_enabled: truein yourconfig.yaml. Or toggle "Enable container lifecycle controls" under Settings -> Discovery. The checkbox is disabled until the socket is writable. - Optional: set the minimum role for the controls.
discovery.docker.lifecycle_min_roledefaults toadmin. Set it topower-useroruserto widen access. - Optional: narrow who can use the controls. Set
discovery.docker.lifecycle_allowed_groupsto additionally require membership in specific groups. These are user and identity-provider group names (built-in user groups, the OIDC groups claim, the forward-auth groups header), not dashboard groups. Renaming or deleting a dashboard group never touches this list. - Optional: set
discovery.docker.health_badge_placementtooverview_and_navto show container state badges in the navigation sidebar as well as the overview (default isoverview;offhides them).
Once the controls are enabled, Docker-tracked apps on the overview show the Docker logo (to admins only; hide it with navigation.show_docker_badge: false, see Navigation > Docker Badge). When the container needs a glance, the card also shows a small status dot: red for stopped, amber for unhealthy or paused, blue for restarting. A healthy, running container shows no dot, so cards stay quiet by default. When you hover over the card, the action buttons appear in a footer below it (Start when stopped, Stop and Restart when running). On touch devices, the buttons stay visible. The footer sits outside the card's open-app area, so a tap to open the app can't trigger a container action by accident. Stop and Restart prompt for confirmation. Start fires immediately.
Muximux writes every action to the audit log, with the caller's username, app name, container id, and outcome (source=audit). That covers successes, failures and denied attempts (role floor not met, group mismatch, socket read-only, lifecycle disabled).
Getting Started
Features
- Apps
- HTTP Actions
- Reverse Proxy
- Docker Discovery
- Docker Labels
- Docker Swarm & Compose
- Navigation
- Split View
- Themes
- Keyboard Shortcuts
- Keyboard & Accessibility
- Health Monitoring
- Icons
- Translations
Security
Identity provider guides
Operations