Connect Muximux to a Docker daemon and it can enumerate running containers, propose them as apps, and keep their URLs current as IPs shift across restarts. Off by default because it requires read access to the Docker socket.

• Scan: lists running containers and proposes a name, icon, URL, port, and group for each, with confidence ratings (high / medium / low).
• Import: one-click adds the chosen containers 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 (default 60s) re-resolves each tracked container against the daemon and rewrites the saved URL if the container's IP changes. Caddy reloads once per tick when gateway-site URLs change.
• Auto-import (optional): with discovery.docker.auto_import set to add/update/sync, Muximux imports every container that carries at least one muximux.* label (a muximux.discovery.id alone is enough) and does not carry muximux.app.enabled=false, with no modal and no click. Unlabelled containers are never auto-imported. add imports each new labeled container once; update also re-syncs an imported app when its labels change; sync additionally removes an imported app when its container disappears or opts out. Off by default. See Automatic Import.
• Detach / Re-link: per-row controls in Settings → Discovery let you stop auto-managing an entry or re-point 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 enumerate) ❌ 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)

1. Settings → Discovery: tick Enable Docker discovery, pick a Network strategy, click Test connection. The banner turns green when Muximux can reach the daemon and identify enough about itself to use the chosen strategy.

2. Apps tab (or Gateway tab) → Discover from Docker: the modal lists every running container the daemon returned (Muximux's own container is excluded so you can't accidentally import yourself as an app). Each row shows:

   • Suggested name, icon, group (catalog-recognised images get these auto-filled at "medium" confidence)
   • Stable tracking key (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-recreate or 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 is lenient about operator prefix conventions: a container named homelab-sonarr, homelab_radarr, or prod.plex still picks up the matching catalog entry just like a bare sonarr / radarr / plex would. Tokens are split on -, _, and .; comparison is exact-token (so transmissionic doesn't masquerade as transmission). Multi-word app names like home-assistant work via an adjacent-pair fallback.

3. Pick routing per row and click Import:

   • Direct - menu links to http://<container-ip>:<port> directly
   • Proxy - menu links via Muximux's /proxy/<slug> path-prefix reverse proxy
   • Gateway domain - menu links to https://<your-subdomain>; requires also creating the gateway site in the same row

   If a row's group does not exist yet, the import creates it in the same save (see Groups are created automatically).

   A container that is already tracked shows a Tracked chip in the Discover dialog, naming what tracks it (an app, an auto-imported app, a gateway site or a quarantined entry, plus the endpoint when it differs). Its row cannot be selected, since it cannot be imported again. A row whose name is used by another app shows "Name already in use by another app".

4. Settings → Discovery → Currently tracked: every imported app or gateway site appears here. Per-row Detach 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 its container cannot be found on the daemon. Invalid Docker-owned entries that were not loaded 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 :rw socket)
    lifecycle_min_role: admin               # min role for lifecycle controls
    lifecycle_allowed_groups: []            # additionally require group membership
    health_badge_placement: overview        # overview | overview_and_nav | off

How you grant Muximux access to the Docker daemon depends on how you run Muximux. The endpoint: field in config.yaml is auto-populated to the platform default if you leave it blank, 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 = discovery only (read-only). Use :rw instead to also enable
      # start/stop/restart controls -- see "Container lifecycle controls" below.
      - /var/run/docker.sock:/var/run/docker.sock:ro

That's the whole prerequisite. The entrypoint stats the bind-mounted socket at startup, reads its group ownership from the host, and adds the runtime user to a matching group inside the container - so the non-root muximux process can actually read the socket. No DOCKER_GID env var, no group_add, no hunting for the right number. The default endpoint: unix:///var/run/docker.sock already matches the mount.

The trailing :ro is the default and keeps Muximux read-only: with :ro it can see and list your containers but cannot start, stop, or change any of them. Marking the mount read-only means a compromised Muximux can't pivot to full daemon control. The Docker engine API still exposes enough surface to enumerate every container on the host, so treat this mount as "effective host root for read" and gate the dashboard accordingly with auth.

Container lifecycle controls (start / stop / restart, see below) are opt-in through two layers: the socket must be mounted :rw and discovery.docker.lifecycle_enabled: true must be set. Neither one alone is enough - the dashboard still won't start, stop, or restart anything until you turn on both. 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). Every action, and every blocked attempt, is written to the audit log.

For rootless Docker, docker-socket-proxy sidecars, or custom socket paths, two override env vars are available: DOCKER_SOCKET (the path the entrypoint stats) and DOCKER_GID (bypass auto-detect and force a specific GID). Almost no one needs these.

There's no container in this path, so no entrypoint script. Linux's normal socket permissions apply: the OS user the binary runs as 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.

For systemd unit installs, you can also encode it directly in the unit:

[Service]
User=muximux
SupplementaryGroups=docker
ExecStart=/usr/local/bin/muximux --data /var/lib/muximux

The 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", the symlink isn't created. Either re-enable that toggle, or point endpoint: at the per-user socket Docker Desktop still maintains:

discovery:
  docker:
    endpoint: unix:///Users/<your-user>/.docker/run/docker.sock

Docker on Windows exposes a named pipe rather than a unix socket. Muximux 3.1.0+ supports the npipe:// scheme natively and uses it by default when running on Windows - no extra config needed:

discovery:
  docker:
    enabled: true
    # endpoint is auto-filled to npipe:////./pipe/docker_engine on Windows

If the Windows account that runs Muximux is a member of the docker-users group, that's sufficient.

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.pem

The remote daemon must expose its API with TLS (dockerd --tlsverify), and the cert/key paths must be readable by the Muximux process.

Strategy gating: when Muximux runs natively (not in a container), container_ip and container_dns need a network_filter to substitute for self-identification. 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. A fully-labelled container goes from docker compose up to a fully-configured Muximux entry with a single click in the Discover modal, no post-import editing -- or with no click at all if you turn on automatic import. 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.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,admins

The 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, so 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 -- name, icon, group, port, and health come from the catalog:

services:
  sonarr:
    image: linuxserver/sonarr
    labels:
      - muximux.discovery.id=sonarr

An 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=8080

An 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=true

Published 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=true

A 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. The app URL (built from port + path) is the request target:

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=true

Restricted 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=ops

Your 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=/ping

Sonarr opens at https://sonarr.example.com. The health check calls http://<container IP>:8989/ping, and the poller keeps that address current when the container's IP changes (logging "Docker health address refreshed"); the app URL is never rewritten. A relative health label is resolved against the container; an absolute URL label is kept as written and never rewritten. 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 an edit made in Settings is overwritten. To pin it, set muximux.app.health to an absolute URL, which is kept as written.

Removing muximux.app.url later returns the app 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 removing 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. Auto-imported apps get it reset by auto-import.

muximux.app.icon and muximux.group.icon take the same values:

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 server exist in both sets; write lucide:server. A bare value containing :, /, \, ?, # or whitespace is not a slug and is ignored (since 3.6.1); use the dashboard:, 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 https URL with a host, no credentials or spaces, and at most 2048 characters. Muximux's Content-Security-Policy only allows images over https, so http URLs and other schemes such as javascript:, data: and file: are refused. The browser loads a URL icon straight from that address (Muximux does not proxy or cache it), so the host must be reachable from the browser.
• An invalid value is ignored: the scan notes it, one warning is logged each time it changes, the stored icon is kept, and discovery carries on.
• Custom uploads cannot be named by a label.

A bare muximux.app.icon value is a Dashboard Icons slug -- the icon filename without its extension (sonarr.svg becomes sonarr). Because the label flow has no GUI in front of you, 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/dashboard returns 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, yes or on and false for false, 0, no or off (case-insensitive, surrounding spaces ignored). Any other value, including an empty one, is ignored and reported in the Discover modal. This applies to every boolean label (enabled, default, proxy, proxy_skip_tls_verify, allow_notifications, health_check, http_action_confirm, http_action_show_toast and the muximux.gateway.* ones), so a misspelt muximux.app.enabled=tru does not opt the container out. A misspelt or empty value keeps the app or gateway site's current setting on update and sync (a typo or an undefined template variable in muximux.gateway.require_auth never 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. Each ignored value is listed in the Discover modal's notes for the container and logged as a warning once, until it changes.
• Labels that are set win while an app is tracked. On apps you imported by hand, muximux.app.name, icon, group and order are re-synced on every refresh, whatever the auto_import mode. Auto-imported apps are re-synced from all their labels under update/sync and left alone under off and add. The muximux.group.* labels apply to groups 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.

These describe the group the container's app is in. They apply only to a group Docker discovery created; see Group labels.

Unknown muximux.* labels are surfaced in the Discover modal's per-row notes so a typo is visible, not 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 enabled, Muximux imports every container that carries at least one muximux.* label (and is not opted out) by itself -- no modal, no click -- and keeps the imported apps in step with the labels over time.

Security -- read before enabling. Auto-import is off by default and only the host operator (who controls config.yaml or the environment) can turn it on. Once on, any container on the shared Docker socket can write itself into your config with no review step -- including a muximux.app.gateway.domain label that publishes a public HTTPS subdomain with an auto-issued ACME certificate. Treat enabling this as trusting every label on every container the daemon can see. If you don't control all of those containers, leave it off and 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:

• off -- today's behavior. Labeled containers are suggestions only; nothing is written until you click Import.
• add -- a newly labeled container is imported one time, then never touched again. Good for bootstrapping.
• update -- like add, plus Muximux re-syncs the app's fields from the labels whenever they change. Never removes anything.
• sync -- like update, plus when a tracked container disappears from the daemon, or opts out with muximux.app.enabled=false, the auto-imported app (and its gateway site) is removed. 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; apps you imported by hand or detached are never touched. 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=sync

The 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) and its save merges onto the stored config, so fields it does not show are kept. On Windows, npipe:// endpoints can be entered in Settings.

A container with muximux.app.enabled=false is excluded from auto-import and hidden from the Discover modal. Use it to keep a labelled container off the dashboard without stripping its labels. Under sync an app already auto-imported from that container, and its gateway site, is removed after the grace period; under update it is left 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 only containers with muximux.app.enabled=true are imported; labelled containers without it are skipped as not_enabled. Invalid values of the environment variable are ignored with 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:

When a container loses all its muximux.* labels, its auto-imported app is detached from auto-import: it is kept, its URL is still refreshed, and sync never removes it. It is still tracked, so the label re-sync applies to it if labels come back. The same happens on upgrade to an auto-imported app whose container has no labels, and when explicit opt-in is turned on for containers without enabled=true.

Auto-import never silently clobbers a URL you took manual control of. Changing an auto-imported app's URL -- in Settings, through the API, or in config.yaml directly -- detaches that app from auto-management. 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, re-syncs the value under update/sync, and the app form shows the toggle locked. Remove the label to unlock it. Under update/sync they are re-synced from the labels on the next tick, so the labels remain the source of truth; under add they 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, and it works with auto_import: off. On each refresh tick, for every tracked app whose container is present, Muximux applies these labels when they are set on the container:

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). An app you detached (Detach in Settings), or an untracked app you created yourself in Settings, is never touched.
• The re-sync only updates apps that are already tracked. It never imports a container or removes an app, whatever the auto_import mode.
• Auto-imported apps follow their auto_import mode instead (re-synced under update/sync, left alone under off and add), so no field is written twice.
• If you rename a group in Settings while a container's muximux.app.group label still names the old group, the label re-creates the old group on the next tick. Change the label too.
• A label is held back, and a warning is logged once, when it cannot be applied: the name is already used by another app (names are compared like proxy paths, so TV and tv collide), or the name is over 100 characters. The app keeps its current value until the conflict is resolved.
• If saving the config fails, the whole tick is rolled back and retried 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, and applies to a group from a muximux.app.group label as well as a catalog group.

• An existing group is matched by name first, then ignoring case and spacing, so media, Media and media-server / Media Server never create a near-duplicate. The app is stored 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. It is placed after your existing groups, in the order the apps were processed. Customise it in Settings like any other group.
• While a tracked app has muximux.app.group set, a group you delete is created again on the next tick. Remove the label or detach the app to stop that.
• If the save fails, the new groups are rolled back together with the apps.
• An app whose group is missing anyway (for example a group removed from config.yaml by hand) is never hidden: 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 (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. A group made by an import, auto-import or the label re-sync is marked as Docker-managed (docker_managed: true in config.yaml). The labels are applied when the group is created and re-synced on every tick while it stays managed. A group you created yourself is never touched.
• 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 it only when the order comes from a muximux.group.order label; a managed group whose order no label sets can be reordered freely and stays managed. Once the marker is cleared the group is yours and later label changes are ignored. Renaming or expanding/collapsing the group does not count. Set docker_managed: true in config.yaml to hand a group back to the labels.
• 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, with one warning per change and a scan note.
• The labels are read from the containers of tracked apps and of tracked gateway sites (through the site's linked app), whatever the auto_import mode. 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, the group changes are rolled back 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. Gateway labels that change the app's URL -- muximux.app.gateway.domain and muximux.gateway.tls -- and 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 -- all propagate on the next tick. Toggling muximux.gateway.require_auth on a running container, for example, is re-synced 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: health check, auth bypass, access, scale, pinned, proxy headers and other per-app settings are kept.

Upgrade note: earlier versions created a gateway site <name>.<your domain> for every labelled container when server.tls.domain was set. 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.

Removing the muximux.app.gateway.domain label from an already-imported container reverts its app to the direct container URL and drops the now-orphaned gateway site on the next tick.

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:

Swarm tasks and Compose services therefore no longer need muximux.discovery.id for stability. Existing name: keys are migrated to the stable key automatically on the first refresh (a Docker tracking key migrated audit line is logged). 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. Duplicates left by earlier redeploys are cleaned by sync.

There is one app per key: Swarm replicas and the containers of a scaled Compose service (--scale) are collapsed 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.labels are service labels and are read too; container labels win when both set the same key.
• Published ports come from the service, so the host_port and host_docker_internal strategies work with ingress-published ports.
• container_dns uses 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 needs muximux.app.port.
• Behind a socket proxy such as tecnativa/docker-socket-proxy, allow /services with SERVICES=1. Without it Muximux logs one warning ("Swarm services unavailable; using task data only") and uses task data only, so service labels and published ports are missing.

An invalid Docker-owned entry in config.yaml (an auto-imported app or gateway site that fails validation, for example one written without a URL by an older version) no longer stops Muximux from starting and no longer rejects a save from Settings. Instead it 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.

Fix the container's labels and the next refresh replaces the entry, or remove it from the list (Remove or Remove all). Removing deletes the entry from config.yaml; a live app or gateway site that shares its tracking key stays tracked. A quarantined entry is also superseded, and dropped from config.yaml at the next save (logged as "Quarantined entry superseded by a live entry"), when a live app takes its name or slug or a live gateway site takes its domain; a quarantined site goes with its superseded app. Under sync, a quarantined app whose container is gone from the polled endpoint is removed 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 that applies to discovery: image names whose last segment is generic (server, app, web, api and similar) no longer match a catalog entry, apps whose names differ only by case or spacing are deduplicated, and a tracked container that cannot be found is logged once when it goes missing 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. An auto-imported app whose container has no labels is detached from auto-import on the first refresh under update/sync: the app stays and its URL keeps refreshing, but sync no longer removes it. Add a label (muximux.discovery.id is enough) if you want the container managed again. See Containers that lose their labels.
• New tracking keys for Swarm and Compose. Keys become swarm:<service> and compose:<project>:<service> and existing name: keys are migrated in place on the first refresh (logged as Docker tracking key migrated). Entries tracked on another endpoint are migrated after Re-link. See Tracking keys.
• Swarm app names. Under update/sync, an auto-imported Swarm app without muximux.app.name is renamed from the task name to the service name, which 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, group or order label now wins on every tracked app, in every mode including off, so an edit to those fields in Settings is reset on the next refresh. 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.yaml is quarantined (kept in the file, not loaded) with a warning. See Quarantined entries.
• sync removes 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, api and similar) no longer match a catalog entry by that segment, so such a container may need muximux.app.name, icon and port labels.
• lifecycle_allowed_groups holds 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_IMPORT and MUXIMUX_DISCOVERY_REQUIRE_EXPLICIT_ENABLE now also apply on a first start without config.yaml. A container that relied on them being ignored there will see them take effect.
• A muximux.app.health value starting with // or /\ is ignored.
• A bare muximux.app.icon (or muximux.group.icon) value is trimmed, then refused as a Dashboard Icons slug if it still contains :, /, \, ?, #, whitespace or control characters; use the dashboard:, 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, rewrites HTML/CSS/JS paths, isolates window.parent, etc. - makes apps work in iframes that refuse them.
• 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 binds 80/443, provisions the certificate via Let's Encrypt, and 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.

If you already run an edge proxy (Cloudflare Tunnel, an upstream Traefik/nginx) and would rather it terminate TLS, set server.gateway_listen: ":8443" and have that proxy forward to Muximux on that port instead. In that case the flow is Browser → upstream proxy → muximux:8443 → http://192.168.1.4:8989.

When an App or GatewaySite is tracked, the URL field is read-only in the editor with an amber lock badge. Muximux protects your edits across all three ways you might change the URL:

1. 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; saving afterwards keeps it detached.
2. Through the API, if a SaveConfig request changes the URL of a tracked entry, Muximux treats that as a deliberate takeover, drops the tracking, and writes an audit log entry.
3. In config.yaml by hand, the same thing happens at next boot: Muximux notices your URL differs from the one the poller last wrote, 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: docker_key, docker_endpoint, docker_strategy and docker_managed_url in a SaveConfig or per-app PUT are ignored and the stored values kept. 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.

Apps with a fixed muximux.app.url are not rewritten by the poller; their docker_managed_url equals the label URL. Their health_url is refreshed from the container on every tick, so a health address edited in Settings is overwritten 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 hand-author a tracked entry from scratch, just set docker_managed_url to the same value as url (or backend_url for a gateway site) so the file-edit detach mechanism has a baseline to compare against.

Caddy's reload is transactional only at the parse step. Post-parse failures (listener collision, async cert provisioning, module panic) can leave the running config in an indeterminate state. The refresh poller handles this with rollback:

• Candidate reload fails, rollback reload succeeds → audit log warning, refresh tick skipped
• Both fail → divergence counter increments, sticky red banner appears in Settings → Discovery
• First clean tick after a divergence → banner transitions to amber "recovered"

The banner gives you a one-glance signal 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).

Caddy binds 80/443 with auto-HTTPS by default, which 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 here

See 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.

All endpoints are admin-only except GET /api/discovery/docker-state, which returns the container state of the apps the caller 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:

1. Edit docker-compose.yml and switch the Docker socket mount from :ro to :rw -- change the line to - /var/run/docker.sock:/var/run/docker.sock:rw. The :ro mount stays as the documented default; you opt in by changing this one character.
2. Set discovery.docker.lifecycle_enabled: true in your config.yaml, or toggle "Enable container lifecycle controls" under Settings -> Discovery (the checkbox is disabled until the socket is writable).
3. Optional: narrow who can use the controls. discovery.docker.lifecycle_min_role defaults to admin; set it to power-user or user to widen access. Set discovery.docker.lifecycle_allowed_groups to 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.
4. Optional: set discovery.docker.health_badge_placement to overview_and_nav to show container state badges in the navigation sidebar as well as the overview (default is overview; off hides them).

Once 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) plus a small status dot when the container needs a glance: red for stopped, amber for unhealthy or paused, blue for restarting (a healthy, running container shows no dot - quiet by default). Hovering the card reveals the action buttons 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.

Every action - success, failure, and denied attempt (role floor not met, group mismatch, socket read-only, lifecycle disabled) - is audit-logged with the caller's username, app name, container id, and outcome (source=audit).