Apus can use Bonjour (mDNS/DNS-SD) to discover an active gateway (WebSocket endpoint). Multicast local. browsing is a LAN-only convenience: the bundled bonjour plugin owns LAN advertising, auto-starting on macOS hosts and opt-in on Linux, Windows, and containerized gateway deployments. The same beacon can also publish through a configured wide-area DNS-SD domain for cross-network discovery. Discovery is best-effort and does not replace SSH or Tailnet-based connectivity.

Wide-area Bonjour (Unicast DNS-SD) over Tailscale

If the node and gateway are on different networks, multicast mDNS can't cross the boundary. Keep the same discovery UX by switching to unicast DNS-SD ("Wide-Area Bonjour") over Tailscale:

  1. Run a DNS server on the gateway host, reachable over the Tailnet.
  2. Publish DNS-SD records for _apus-gw._tcp under a dedicated zone (example: apus.internal.).
  3. Configure Tailscale split DNS so your chosen domain resolves via that DNS server for clients, including iOS.

apus.internal. above is just an example — Apus supports any discovery domain. iOS/Android nodes browse both local. and your configured wide-area domain.

Gateway config

{
  gateway: { bind: "tailnet" }, // tailnet-only (recommended)
  discovery: { wideArea: { domain: "apus.internal" } },
}

Setting discovery.wideArea.domain enables Gateway wide-area publishing. The APUS_WIDE_AREA_DOMAIN environment variable supplies a default for CLI discovery and DNS setup; it does not enable Gateway publishing by itself.

One-time DNS server setup (gateway host, macOS only)

apus dns setup --apply

This command is macOS-only and requires Homebrew and a running Tailscale connection. It installs CoreDNS (brew install coredns) and configures it to:

Run without --apply first to preview the plan (domain, zone file path, detected Tailnet IP, recommended config) without installing anything.

Validate from a Tailnet-connected machine:

dns-sd -B _apus-gw._tcp apus.internal.
dig @<TAILNET_IPV4> -p 53 _apus-gw._tcp.apus.internal PTR +short

Tailscale DNS settings

In the Tailscale admin console:

Once clients accept Tailnet DNS, iOS nodes and CLI discovery can browse _apus-gw._tcp in your discovery domain without multicast.

Gateway listener security

The gateway WS port (default 18789) binds to loopback by default. For LAN/Tailnet access, bind explicitly and keep auth enabled. For Tailnet-only setups, set gateway.bind: "tailnet" in ~/.apus/apus.json and restart the gateway (or the macOS menubar app).

What advertises

Only the gateway advertises _apus-gw._tcp. LAN multicast advertising comes from the bundled bonjour plugin when enabled; wide-area DNS-SD publishing stays gateway-owned.

Service types

TXT keys (non-secret hints)

Key When present
role=gateway Always.
displayName=<friendly name> Always.
lanHost=<hostname>.local Always.
gatewayPort=<port> Always (gateway WS + HTTP).
transport=gateway Always.
gatewayTls=1 Only when TLS is enabled.
gatewayTlsSha256=<sha256> Only when TLS is enabled and a fingerprint is available.
gatewayDirectReachable=1 Only when the gateway is directly reachable (not only via a relay/proxy path).
tailnetDns=<magicdns> mDNS full mode only; optional hint when Tailnet is available.
sshPort=<port> Full mode only; omitted in minimal and off modes.
cliPath=<path> Full mode only; omitted in minimal and off modes.

Security notes:

The macOS app treats the resolved endpoint as a hint too. Selecting Nearby Gateways opens the connection editor; it does not authenticate to the advertised destination, change a saved route, or import SSH details or a certificate pin. Supply a trusted address, SSH target, or owner-provided setup code, then save the connection. See Configure in the app.

Debugging on macOS

Built-in tools:

# Browse instances
dns-sd -B _apus-gw._tcp local.

# Resolve one instance (replace <instance>)
dns-sd -L "<instance>" _apus-gw._tcp local.

If browsing works but resolving fails, you're usually hitting a LAN policy or mDNS resolver issue.

Debugging in Gateway logs

The gateway writes a rolling log file (printed on startup as gateway log file: ...). Look for bonjour: lines, especially:

Apus starts each Bonjour service once and leaves checking, retry, name-conflict resolution, and interface-change republishing to the mDNS responder. This avoids overlapping publish attempts during normal network churn. Repeated internal self-check messages are suppressed so they cannot flood the gateway log, as are transient ENODEV MDNS socket warnings that occur when a network interface (for example a short-lived Docker bridge) is removed between the responder's interface polls.

When multiple Apus gateways advertise from the same host, Bonjour may append suffixes such as (2) or (3) to keep service instance names unique. Those suffixes are normal conflict resolution.

Bonjour uses the system hostname for the advertised .local host when it's a valid DNS label. If the system hostname contains spaces, underscores, or another invalid DNS-label character, Apus falls back to apus.local. Set APUS_MDNS_HOSTNAME=<name> before starting the gateway when you need an explicit host label.

Debugging on iOS node

The iOS node uses NWBrowser to discover _apus-gw._tcp.

To capture logs: Settings -> Gateway -> Advanced -> Discovery Debug Logs, then Settings -> Gateway -> Advanced -> Discovery Logs -> reproduce -> Copy. The log includes browser state transitions and result-set changes.

When to enable Bonjour

Bonjour auto-starts for empty-config gateway startup on macOS hosts, since the local app and nearby iOS/Android nodes commonly rely on same-LAN discovery.

Enable it explicitly when same-LAN auto-discovery is useful on Linux, Windows, or another non-macOS host:

apus plugins enable bonjour

When enabled, Bonjour uses discovery.mdns.mode to decide how much TXT metadata to publish; the same mode controls optional TXT hints in wide-area DNS-SD records. Modes:

Mode Behavior
minimal (default) Core TXT keys only; omits sshPort, cliPath, tailnetDns.
full Adds sshPort, cliPath, tailnetDns — use when clients need those hints.
off Suppresses LAN multicast without changing plugin enablement; wide-area DNS-SD can still publish when discovery.wideArea.domain is set.

Mode changes hot-apply without restarting the Gateway or disconnecting clients. The discovery owner stops the prior advertisements before publishing the new mode. Reducing disclosure also updates TXT hints in any configured wide-area DNS-SD zone. Changing the mode does not enable a disabled Bonjour plugin.

When to disable Bonjour

Leave Bonjour disabled when LAN multicast advertising is unnecessary, unavailable, or harmful — common cases are non-macOS servers, Docker bridge networking, WSL, or a network policy that drops mDNS multicast. The gateway stays reachable through its published URL, SSH, Tailnet, or wide-area DNS-SD; only LAN auto-discovery is unreliable.

Use the env override for deployment-scoped problems (safe for Docker images, service files, launch scripts, one-off debugging — it disappears when the environment does):

APUS_DISABLE_BONJOUR=1

Use plugin configuration when you intentionally want to turn off the bundled LAN discovery plugin for that Apus config:

apus plugins disable bonjour

Docker gotchas

The bundled Bonjour plugin auto-disables LAN multicast advertising in detected containers when APUS_DISABLE_BONJOUR is unset. Docker bridge networks usually don't forward mDNS multicast (224.0.0.251:5353) between the container and the LAN, so advertising from the container rarely makes discovery work.

Gotchas:

Troubleshooting disabled Bonjour

If a node no longer auto-discovers the gateway after Docker setup:

  1. Confirm whether the gateway is running in auto, forced-on, or forced-off mode:

    docker compose config | grep APUS_DISABLE_BONJOUR

  2. Confirm the gateway itself is reachable through the published port:

    curl -fsS http://127.0.0.1:18789/healthz

  3. Use a direct target when Bonjour is disabled:

    • Control UI or local tools: http://127.0.0.1:18789
    • LAN clients: http://<gateway-host>:18789
    • Cross-network clients: Tailnet MagicDNS, Tailnet IP, SSH tunnel, or wide-area DNS-SD

  4. If you deliberately enabled the Bonjour plugin in Docker and forced advertising with APUS_DISABLE_BONJOUR=0, test multicast from the host:

    dns-sd -B _apus-gw._tcp local.

    If browsing is empty, or Gateway logs show repeated ciao check failures, restore APUS_DISABLE_BONJOUR=1 and use a direct or Tailnet route.

Common failure modes

Escaped instance names (\032)

Bonjour/DNS-SD often escapes bytes in service instance names as decimal \DDD sequences (spaces become \032). This is normal at the protocol level; UIs should decode for display (iOS uses BonjourEscapes.decode).

Enabling / disabling / configuration

Setting Effect
apus plugins enable bonjour Enables the bundled LAN discovery plugin on hosts where it isn't default-enabled.
apus plugins disable bonjour Disables LAN multicast advertising by disabling the bundled plugin.
APUS_DISABLE_BONJOUR=1 (or true/yes/on) Disables LAN multicast advertising without changing plugin config.
APUS_DISABLE_BONJOUR=0 (or false/no/off) Forces LAN multicast advertising on, including inside detected containers.
discovery.mdns.mode off | minimal (default) | full — see modes above.
gateway.bind Controls the gateway bind mode in ~/.apus/apus.json.
APUS_SSH_PORT Overrides the SSH port when sshPort is advertised (full mode).
APUS_TAILNET_DNS Publishes a MagicDNS hint in TXT when mDNS full mode is enabled.
APUS_CLI_PATH Overrides the advertised CLI path (full mode).

macOS hosts auto-start the bundled LAN discovery plugin by default. When the Bonjour plugin is enabled and APUS_DISABLE_BONJOUR is unset, Bonjour advertises on normal hosts and auto-disables inside detected containers (Docker, Fly.io machines, and common container runtimes).

Related docs