---
summary: "Bonjour/mDNS discovery + debugging (Gateway beacons, clients, and common failure modes)"
read_when:
  - Debugging Bonjour discovery issues on macOS/iOS
  - Changing mDNS service types, TXT records, or discovery UX
title: "Bonjour Discovery"
---

# Bonjour / mDNS discovery

Fased uses Bonjour (mDNS / DNS-SD) as a **LAN-only convenience** to discover an
active Gateway WebSocket endpoint. It is best-effort. Use SSH or Tailnet-based
connectivity for reliable remote access.

## Wide‑area Bonjour (Unicast DNS‑SD) over Tailscale

If the node and gateway are on different networks, multicast mDNS won’t cross the
boundary. You can keep the same discovery UX by switching to **unicast DNS‑SD**
("Wide‑Area Bonjour") over Tailscale.

High‑level steps:

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

Fased supports any discovery domain; `fased.internal.` is just an example.
iOS/Android nodes browse both `local.` and your configured wide‑area domain.

### Gateway config (recommended)

```json5
{
  gateway: { bind: "tailnet" }, // tailnet-only (recommended)
  discovery: {
    wideArea: { enabled: true, domain: "fased.internal" },
  },
}
```

### One‑time DNS server setup (gateway host)

```bash
fased dns setup --apply
```

On macOS/Homebrew hosts, `--apply` installs CoreDNS and configures it to:

- listen on port 53 only on the gateway’s Tailscale interfaces
- serve your chosen domain from `~/.fased/dns/<domain>.db`
  (example: `fased.internal.`)

Validate from a tailnet‑connected machine:

```bash
dns-sd -B _fased-gw._tcp fased.internal.
dig @<TAILNET_IPV4> -p 53 _fased-gw._tcp.fased.internal PTR +short
```

### Tailscale DNS settings

In the Tailscale admin console:

- Add a nameserver pointing at the gateway’s tailnet IP (UDP/TCP 53).
- Add split DNS so your discovery domain uses that nameserver.

Once clients accept tailnet DNS, iOS nodes can browse
`_fased-gw._tcp` in your discovery domain without multicast.

### Gateway listener security (recommended)

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 `~/.fased/fased.json`.
- Restart the Gateway (or restart the macOS menubar app).

## What advertises

Only the Gateway advertises `_fased-gw._tcp`.

## Service types

- `_fased-gw._tcp` — gateway transport beacon (used by macOS/iOS/Android nodes).

## TXT keys (non‑secret hints)

The Gateway advertises small non‑secret hints to make UI flows convenient:

- `role=gateway`
- `displayName=<friendly name>`
- `lanHost=<hostname>.local`
- `gatewayPort=<port>` (Gateway WS + HTTP)
- `gatewayTls=1` (only when TLS is enabled)
- `gatewayTlsSha256=<sha256>` (only when TLS is enabled and fingerprint is
  available)
- `canvasPort=<port>` (only when the canvas host is enabled; currently the same
  as `gatewayPort`)
- `sshPort=<port>` (only in `discovery.mdns.mode: "full"`)
- `transport=gateway`
- `cliPath=<path>` (only in `discovery.mdns.mode: "full"`)
- `tailnetDns=<magicdns>` (optional hint when Tailnet is available)

Security notes:

- Bonjour/mDNS TXT records are **unauthenticated**. Clients should treat them as
  hints, not authoritative routing.
- Route using the resolved service endpoint: SRV plus A/AAAA records.
- Treat `lanHost`, `tailnetDns`, `gatewayPort`, and `gatewayTlsSha256` as hints
  only.
- TLS pinning must keep the previously stored pin when an advertised
  `gatewayTlsSha256` changes.
- iOS/Android nodes should treat discovery-based direct connects as
  **TLS-only** and require explicit user confirmation before trusting a
  first-time fingerprint.

## Debugging on macOS

Useful built‑in tools:

- Browse instances:

  ```bash
  dns-sd -B _fased-gw._tcp local.
  ```

- Resolve one instance (replace `<instance>`):

  ```bash
  dns-sd -L "<instance>" _fased-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:

- `bonjour: advertise failed ...`
- `bonjour: ... name conflict resolved` / `hostname conflict resolved`
- `bonjour: watchdog detected non-announced service ...`

## Debugging on iOS node

The iOS node uses `NWBrowser` to discover `_fased-gw._tcp`.

To capture logs:

- Settings → Gateway → Advanced → **Discovery Debug Logs**
- Settings → Gateway → Advanced → **Discovery Logs** → reproduce → **Copy**

The log includes browser state transitions and result‑set changes.

## Common failure modes

- **Bonjour doesn’t cross networks**: use Tailnet or SSH.
- **Multicast blocked**: some Wi‑Fi networks disable mDNS.
- **Sleep / interface churn**: macOS may temporarily drop mDNS results; retry.
- **Browse works but resolve fails**: keep machine names simple (avoid emojis or
  punctuation), then restart the Gateway. The service instance name derives from
  the host name, so overly complex names can confuse some resolvers.

## Escaped instance names (`\032`)

Bonjour/DNS‑SD often escapes bytes in service instance names as decimal `\DDD`
sequences (e.g. spaces become `\032`).

- This is normal at the protocol level.
- UIs should decode for display (iOS uses `BonjourEscapes.decode`).

## Disabling / configuration

- `FASED_DISABLE_BONJOUR=1` disables advertising.
- `discovery.mdns.mode: "off"` disables mDNS from config.
- `discovery.mdns.mode: "minimal"` is the default and omits `sshPort`/`cliPath`.
- `discovery.mdns.mode: "full"` includes `sshPort`/`cliPath`.
- `gateway.bind` in `~/.fased/fased.json` controls the Gateway bind mode.
- `FASED_SSH_PORT` overrides the SSH port advertised in full TXT mode.
- `FASED_TAILNET_DNS` publishes a MagicDNS hint in TXT.
- `FASED_CLI_PATH` overrides the advertised CLI path in full TXT mode.

## Related docs

- Discovery policy and transport selection: [Discovery](/gateway/discovery)
- Node pairing + approvals: [Gateway pairing](/gateway/pairing)
