nodmix 2026.5.25

package/docs/gateway/authentication.md

@@ -0,0 +1,239 @@
+---
+summary: "Model authentication: OAuth, API keys, Claude CLI reuse, and Anthropic setup-token"
+read_when:
+  - Debugging model auth or OAuth expiry
+  - Documenting authentication or credential storage
+title: "Authentication"
+---
+
+<Note>
+This page is the **model provider** authentication reference (API keys, OAuth, Claude CLI reuse, and Anthropic setup-token). For **gateway connection** authentication (token, password, trusted-proxy), see [Configuration](/gateway/configuration) and [Trusted Proxy Auth](/gateway/trusted-proxy-auth).
+</Note>
+
+Nodmix supports OAuth and API keys for model providers. For always-on gateway
+hosts, API keys are usually the most predictable option. Subscription/OAuth
+flows are also supported when they match your provider account model.
+
+See [/concepts/oauth](/concepts/oauth) for the full OAuth flow and storage
+layout.
+For SecretRef-based auth (`env`/`file`/`exec` providers), see [Secrets Management](/gateway/secrets).
+For credential eligibility/reason-code rules used by `models status --probe`, see
+[Auth Credential Semantics](/auth-credential-semantics).
+
+## Recommended setup (API key, any provider)
+
+If you're running a long-lived gateway, start with an API key for your chosen
+provider.
+For Anthropic specifically, API key auth is still the most predictable server
+setup, but Nodmix also supports reusing a local Claude CLI login.
+
+1. Create an API key in your provider console.
+2. Put it on the **gateway host** (the machine running `nodmix gateway`).
+
+```bash
+export <PROVIDER>_API_KEY="..."
+nodmix models status
+```
+
+3. If the Gateway runs under systemd/launchd, prefer putting the key in
+   `~/.nodmix/.env` so the daemon can read it:
+
+```bash
+cat >> ~/.nodmix/.env <<'EOF'
+<PROVIDER>_API_KEY=...
+EOF
+```
+
+Then restart the daemon (or restart your Gateway process) and re-check:
+
+```bash
+nodmix models status
+nodmix doctor
+```
+
+If you'd rather not manage env vars yourself, onboarding can store
+API keys for daemon use: `nodmix onboard`.
+
+See [Help](/help) for details on env inheritance (`env.shellEnv`,
+`~/.nodmix/.env`, systemd/launchd).
+
+## Anthropic: Claude CLI and token compatibility
+
+Anthropic setup-token auth is still available in Nodmix as a supported token
+path. Anthropic staff has since told us that Nodmix-style Claude CLI usage is
+allowed again, so Nodmix treats Claude CLI reuse and `claude -p` usage as
+sanctioned for this integration unless Anthropic publishes a new policy. When
+Claude CLI reuse is available on the host, that is now the preferred path.
+
+For long-lived gateway hosts, an Anthropic API key is still the most predictable
+setup. If you want to reuse an existing Claude login on the same host, use the
+Anthropic Claude CLI path in onboarding/configure.
+
+Recommended host setup for Claude CLI reuse:
+
+```bash
+# Run on the gateway host
+claude auth login
+claude auth status --text
+nodmix models auth login --provider anthropic --method cli --set-default
+```
+
+This is a two-step setup:
+
+1. Log Claude Code itself into Anthropic on the gateway host.
+2. Tell Nodmix to switch Anthropic model selection to the local `claude-cli`
+   backend and store the matching Nodmix auth profile.
+
+If `claude` is not on `PATH`, either install Claude Code first or set
+`agents.defaults.cliBackends.claude-cli.command` to the real binary path.
+
+Manual token entry (any provider; writes `auth-profiles.json` + updates config):
+
+```bash
+nodmix models auth paste-token --provider openrouter
+```
+
+`auth-profiles.json` stores credentials only. The canonical shape is:
+
+```json
+{
+  "version": 1,
+  "profiles": {
+    "openrouter:default": {
+      "type": "api_key",
+      "provider": "openrouter",
+      "key": "OPENROUTER_API_KEY"
+    }
+  }
+}
+```
+
+Nodmix expects the canonical `version` + `profiles` shape at runtime. If an older install still has a flat file such as `{ "openrouter": { "apiKey": "..." } }`, run `nodmix doctor --fix` to rewrite it as an `openrouter:default` API-key profile; doctor keeps a `.legacy-flat.*.bak` copy beside the original. Endpoint details such as `baseUrl`, `api`, model ids, headers, and timeouts belong under `models.providers.<id>` in `nodmix.json` or `models.json`, not in `auth-profiles.json`.
+
+External auth routes such as Bedrock `auth: "aws-sdk"` are also not credentials. If you want a named Bedrock route, put `auth.profiles.<id>.mode: "aws-sdk"` in `nodmix.json`; do not write `type: "aws-sdk"` into `auth-profiles.json`. `nodmix doctor --fix` moves legacy AWS SDK markers from the credential store into config metadata.
+
+Auth profile refs are also supported for static credentials:
+
+- `api_key` credentials can use `keyRef: { source, provider, id }`
+- `token` credentials can use `tokenRef: { source, provider, id }`
+- OAuth-mode profiles do not support SecretRef credentials; if `auth.profiles.<id>.mode` is set to `"oauth"`, SecretRef-backed `keyRef`/`tokenRef` input for that profile is rejected.
+
+Automation-friendly check (exit `1` when expired/missing, `2` when expiring):
+
+```bash
+nodmix models status --check
+```
+
+Live auth probes:
+
+```bash
+nodmix models status --probe
+```
+
+Notes:
+
+- Probe rows can come from auth profiles, env credentials, or `models.json`.
+- If explicit `auth.order.<provider>` omits a stored profile, probe reports
+  `excluded_by_auth_order` for that profile instead of trying it.
+- If auth exists but Nodmix cannot resolve a probeable model candidate for
+  that provider, probe reports `status: no_model`.
+- Rate-limit cooldowns can be model-scoped. A profile cooling down for one
+  model can still be usable for a sibling model on the same provider.
+
+Optional ops scripts (systemd/Termux) are documented here:
+[Auth monitoring scripts](/help/scripts#auth-monitoring-scripts)
+
+## Anthropic note
+
+The Anthropic `claude-cli` backend is supported again.
+
+- Anthropic staff told us this Nodmix integration path is allowed again.
+- Nodmix therefore treats Claude CLI reuse and `claude -p` usage as sanctioned
+  for Anthropic-backed runs unless Anthropic publishes a new policy.
+- Anthropic API keys remain the most predictable choice for long-lived gateway
+  hosts and explicit server-side billing control.
+
+## Checking model auth status
+
+```bash
+nodmix models status
+nodmix doctor
+```
+
+## API key rotation behavior (gateway)
+
+Some providers support retrying a request with alternative keys when an API call
+hits a provider rate limit.
+
+- Priority order:
+  - `NODMIX_LIVE_<PROVIDER>_KEY` (single override)
+  - `<PROVIDER>_API_KEYS`
+  - `<PROVIDER>_API_KEY`
+  - `<PROVIDER>_API_KEY_*`
+- Google providers also include `GOOGLE_API_KEY` as an additional fallback.
+- The same key list is deduplicated before use.
+- Nodmix retries with the next key only for rate-limit errors (for example
+  `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent
+requests`, `ThrottlingException`, `concurrency limit reached`, or
+  `workers_ai ... quota limit exceeded`).
+- Non-rate-limit errors are not retried with alternate keys.
+- If all keys fail, the final error from the last attempt is returned.
+
+## Removing provider auth while the gateway is running
+
+When provider auth is removed through the Gateway control plane, Nodmix deletes
+the saved auth profiles for that provider and aborts active chat or agent runs
+whose selected model provider matches the removed provider. The aborted runs emit
+the normal chat cancellation and lifecycle events with
+`stopReason: "auth-revoked"`, so connected clients can show that the run was
+stopped because credentials were removed.
+
+Removing saved auth does not revoke keys at the provider. Rotate or revoke the
+key in the provider dashboard when you need provider-side invalidation.
+
+## Controlling which credential is used
+
+### Per-session (chat command)
+
+Use `/model <alias-or-id>@<profileId>` to pin a specific provider credential for the current session (example profile ids: `anthropic:default`, `anthropic:work`).
+
+Use `/model` (or `/model list`) for a compact picker; use `/model status` for the full view (candidates + next auth profile, plus provider endpoint details when configured).
+
+### Per-agent (CLI override)
+
+Set an explicit auth profile order override for an agent (stored in that agent's `auth-state.json`):
+
+```bash
+nodmix models auth order get --provider anthropic
+nodmix models auth order set --provider anthropic anthropic:default
+nodmix models auth order clear --provider anthropic
+```
+
+Use `--agent <id>` to target a specific agent; omit it to use the configured default agent.
+When you debug order issues, `nodmix models status --probe` shows omitted
+stored profiles as `excluded_by_auth_order` instead of silently skipping them.
+When you debug cooldown issues, remember that rate-limit cooldowns can be tied
+to one model id rather than the whole provider profile.
+
+## Troubleshooting
+
+### "No credentials found"
+
+If the Anthropic profile is missing, configure an Anthropic API key on the
+**gateway host** or set up the Anthropic setup-token path, then re-check:
+
+```bash
+nodmix models status
+```
+
+### Token expiring/expired
+
+Run `nodmix models status` to confirm which profile is expiring. If an
+Anthropic token profile is missing or expired, refresh that setup via
+setup-token or migrate to an Anthropic API key.
+
+## Related
+
+- [Secrets management](/gateway/secrets)
+- [Remote access](/gateway/remote)
+- [Auth storage](/concepts/oauth)

package/docs/gateway/background-process.md

@@ -0,0 +1,147 @@
+---
+summary: "Background exec execution and process management"
+read_when:
+  - Adding or modifying background exec behavior
+  - Debugging long-running exec tasks
+title: "Background exec and process tool"
+---
+
+Nodmix runs shell commands through the `exec` tool and keeps long-running tasks in memory. The `process` tool manages those background sessions.
+
+## exec tool
+
+Key parameters:
+
+- `command` (required)
+- `yieldMs` (default 10000): auto-background after this delay
+- `background` (bool): background immediately
+- `timeout` (seconds, default `tools.exec.timeoutSec`): kill the process after this timeout; set `timeout: 0` only to disable the exec process timeout for that call
+- `elevated` (bool): run outside the sandbox if elevated mode is enabled/allowed (`gateway` by default, or `node` when the exec target is `node`)
+- Need a real TTY? Set `pty: true`.
+- `workdir`, `env`
+
+Behavior:
+
+- Foreground runs return output directly.
+- When backgrounded (explicit or timeout), the tool returns `status: "running"` + `sessionId` and a short tail.
+- Background and `yieldMs` runs inherit `tools.exec.timeoutSec` unless the call provides an explicit `timeout`.
+- Output is kept in memory until the session is polled or cleared.
+- If the `process` tool is disallowed, `exec` runs synchronously and ignores `yieldMs`/`background`.
+- Spawned exec commands receive `NODMIX_SHELL=exec` for context-aware shell/profile rules.
+- For long-running work that starts now, start it once and rely on automatic
+  completion wake when it is enabled and the command emits output or fails.
+- If automatic completion wake is unavailable, or you need quiet-success
+  confirmation for a command that exited cleanly without output, use `process`
+  to confirm completion.
+- Do not emulate reminders or delayed follow-ups with `sleep` loops or repeated
+  polling; use cron for future work.
+
+## Child process bridging
+
+When spawning long-running child processes outside the exec/process tools (for example, CLI respawns or gateway helpers), attach the child-process bridge helper so termination signals are forwarded and listeners are detached on exit/error. This avoids orphaned processes on systemd and keeps shutdown behavior consistent across platforms.
+
+Environment overrides:
+
+- `PI_BASH_YIELD_MS`: default yield (ms)
+- `PI_BASH_MAX_OUTPUT_CHARS`: in-memory output cap (chars)
+- `NODMIX_BASH_PENDING_MAX_OUTPUT_CHARS`: pending stdout/stderr cap per stream (chars)
+- `PI_BASH_JOB_TTL_MS`: TTL for finished sessions (ms, bounded to 1m–3h)
+- `NODMIX_PROCESS_INPUT_WAIT_IDLE_MS`: idle-output threshold before writable background sessions are marked as likely waiting for input (default 15000 ms)
+
+Config (preferred):
+
+- `tools.exec.backgroundMs` (default 10000)
+- `tools.exec.timeoutSec` (default 1800)
+- `tools.exec.cleanupMs` (default 1800000)
+- `tools.exec.notifyOnExit` (default true): enqueue a system event + request heartbeat when a backgrounded exec exits.
+- `tools.exec.notifyOnExitEmptySuccess` (default false): when true, also enqueue completion events for successful backgrounded runs that produced no output.
+
+## process tool
+
+Actions:
+
+- `list`: running + finished sessions
+- `poll`: drain new output for a session (also reports exit status)
+- `log`: read the aggregated output and show input recovery hints (supports `offset` + `limit`)
+- `write`: send stdin (`data`, optional `eof`)
+- `send-keys`: send explicit key tokens or bytes to a PTY-backed session
+- `submit`: send Enter / carriage return to a PTY-backed session
+- `paste`: send literal text, optionally wrapped in bracketed paste mode
+- `kill`: terminate a background session
+- `clear`: remove a finished session from memory
+- `remove`: kill if running, otherwise clear if finished
+
+Notes:
+
+- Only backgrounded sessions are listed/persisted in memory.
+- Sessions are lost on process restart (no disk persistence).
+- Session logs are only saved to chat history if you run `process poll/log` and the tool result is recorded.
+- `process` is scoped per agent; it only sees sessions started by that agent.
+- Use `poll` / `log` for status, logs, quiet-success confirmation, or
+  completion confirmation when automatic completion wake is unavailable.
+- Use `log` before recovering an interactive CLI so the current transcript,
+  stdin state, and input-wait hint are visible together.
+- Use `write` / `send-keys` / `submit` / `paste` / `kill` when you need input
+  or intervention.
+- `process list` includes a derived `name` (command verb + target) for quick scans.
+- `process list`, `poll`, and `log` report `waitingForInput` only
+  when the session still has writable stdin and has been idle longer than the
+  input-wait threshold.
+- `process log` uses line-based `offset`/`limit`.
+- When both `offset` and `limit` are omitted, it returns the last 200 lines and includes a paging hint.
+- When `offset` is provided and `limit` is omitted, it returns from `offset` to the end (not capped to 200).
+- Polling is for on-demand status, not wait-loop scheduling. If the work should
+  happen later, use cron instead.
+
+## Examples
+
+Run a long task and poll later:
+
+```json
+{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }
+```
+
+```json
+{ "tool": "process", "action": "poll", "sessionId": "<id>" }
+```
+
+Inspect an interactive session before sending input:
+
+```json
+{ "tool": "process", "action": "log", "sessionId": "<id>" }
+```
+
+Start immediately in background:
+
+```json
+{ "tool": "exec", "command": "npm run build", "background": true }
+```
+
+Send stdin:
+
+```json
+{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }
+```
+
+Send PTY keys:
+
+```json
+{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }
+```
+
+Submit current line:
+
+```json
+{ "tool": "process", "action": "submit", "sessionId": "<id>" }
+```
+
+Paste literal text:
+
+```json
+{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }
+```
+
+## Related
+
+- [Exec tool](/tools/exec)
+- [Exec approvals](/tools/exec-approvals)

package/docs/gateway/bonjour.md

@@ -0,0 +1,303 @@
+---
+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"
+---
+
+Nodmix 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. It auto-starts on macOS hosts and is opt-in on
+Linux, Windows, and containerized Gateway deployments. For cross-network discovery, the same
+beacon can also be published through a configured wide-area DNS-SD domain. Discovery
+is still 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 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 `_nodmix-gw._tcp` under a dedicated zone
+   (example: `nodmix.internal.`).
+3. Configure Tailscale **split DNS** so your chosen domain resolves via that
+   DNS server for clients (including iOS).
+
+Nodmix supports any discovery domain; `nodmix.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 } }, // enables wide-area DNS-SD publishing
+}
+```
+
+### One-time DNS server setup (gateway host)
+
+```bash
+nodmix dns setup --apply
+```
+
+This installs CoreDNS and configures it to:
+
+- listen on port 53 only on the gateway's Tailscale interfaces
+- serve your chosen domain (example: `nodmix.internal.`) from `~/.nodmix/dns/<domain>.db`
+
+Validate from a tailnet-connected machine:
+
+```bash
+dns-sd -B _nodmix-gw._tcp nodmix.internal.
+dig @<TAILNET_IPV4> -p 53 _nodmix-gw._tcp.nodmix.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 and CLI discovery can browse
+`_nodmix-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 `~/.nodmix/nodmix.json`.
+- Restart the Gateway (or restart the macOS menubar app).
+
+## What advertises
+
+Only the Gateway advertises `_nodmix-gw._tcp`. LAN multicast advertising is
+provided by the bundled `bonjour` plugin when the plugin is enabled; wide-area
+DNS-SD publishing remains Gateway-owned.
+
+## Service types
+
+- `_nodmix-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`)
+- `transport=gateway`
+- `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:
+
+- Bonjour/mDNS TXT records are **unauthenticated**. Clients must not treat TXT as authoritative routing.
+- Clients should route using the resolved service endpoint (SRV + A/AAAA). Treat `lanHost`, `tailnetDns`, `gatewayPort`, and `gatewayTlsSha256` as hints only.
+- SSH auto-targeting should likewise use the resolved service host, not TXT-only hints.
+- TLS pinning must never allow an advertised `gatewayTlsSha256` to override a previously stored pin.
+- 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 _nodmix-gw._tcp local.
+  ```
+
+- Resolve one instance (replace `<instance>`):
+
+  ```bash
+  dns-sd -L "<instance>" _nodmix-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: suppressing ciao cancellation ...`
+- `bonjour: ... name conflict resolved` / `hostname conflict resolved`
+- `bonjour: watchdog detected non-announced service ...`
+- `bonjour: disabling advertiser after ... failed restarts ...`
+
+The watchdog treats active `probing`, `announcing`, and fresh conflict-renames as
+in-progress states. If the service never reaches `announced`, Nodmix eventually
+recreates the advertiser and, after repeated failures, disables Bonjour for that
+Gateway process instead of re-advertising forever.
+
+Bonjour uses the system hostname for the advertised `.local` host when it is a
+valid DNS label. If the system hostname contains spaces, underscores, or another
+invalid DNS-label character, Nodmix falls back to `nodmix.local`. Set
+`NODMIX_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 `_nodmix-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.
+
+## When to enable Bonjour
+
+Bonjour auto-starts for empty-config Gateway startup on macOS hosts because the
+local app and nearby iOS/Android nodes commonly rely on same-LAN discovery.
+
+Enable Bonjour explicitly when same-LAN auto-discovery is useful on Linux,
+Windows, or another non-macOS host:
+
+```bash
+nodmix 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.
+The default mode is `minimal`; use `full` only when clients need `cliPath` or
+`sshPort` hints. Use `off` to suppress LAN multicast without changing plugin
+enablement; wide-area DNS-SD can still publish the minimal Gateway beacon when
+`discovery.wideArea.enabled` is true.
+
+## When to disable Bonjour
+
+Leave Bonjour disabled when LAN multicast advertising is unnecessary, unavailable,
+or harmful. The common cases are non-macOS servers, Docker bridge networking,
+WSL, or a network policy that drops mDNS multicast. In those environments the
+Gateway is still reachable through its published URL, SSH, Tailnet, or wide-area
+DNS-SD, but LAN auto-discovery is not reliable.
+
+Prefer the existing environment override when the problem is deployment-scoped:
+
+```bash
+NODMIX_DISABLE_BONJOUR=1
+```
+
+That disables LAN multicast advertising without changing plugin configuration.
+It is safe for Docker images, service files, launch scripts, and one-off
+debugging because the setting disappears when the environment does.
+
+Use plugin configuration when you intentionally want to turn off the bundled LAN
+discovery plugin for that Nodmix config:
+
+```bash
+nodmix plugins disable bonjour
+```
+
+## Docker gotchas
+
+The bundled Bonjour plugin auto-disables LAN multicast advertising in detected
+containers when `NODMIX_DISABLE_BONJOUR` is unset. Docker bridge networks
+usually do not forward mDNS multicast (`224.0.0.251:5353`) between the container
+and the LAN, so advertising from the container rarely makes discovery work.
+
+Important gotchas:
+
+- Bonjour auto-starts on macOS hosts and is opt-in elsewhere. Leaving it
+  disabled does not stop the Gateway; it only skips LAN multicast advertising.
+- Disabling Bonjour does not change `gateway.bind`; Docker still defaults to
+  `NODMIX_GATEWAY_BIND=lan` so the published host port can work.
+- Disabling Bonjour does not disable wide-area DNS-SD. Use wide-area discovery
+  or Tailnet when the Gateway and node are not on the same LAN.
+- Reusing the same `NODMIX_CONFIG_DIR` outside Docker does not persist the
+  container auto-disable policy.
+- Set `NODMIX_DISABLE_BONJOUR=0` only for host networking, macvlan, or another
+  network where mDNS multicast is known to pass; set it to `1` to force-disable.
+
+## 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:
+
+   ```bash
+   docker compose config | grep NODMIX_DISABLE_BONJOUR
+   ```
+
+2. Confirm the Gateway itself is reachable through the published port:
+
+   ```bash
+   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 `NODMIX_DISABLE_BONJOUR=0`, test multicast from the host:
+
+   ```bash
+   dns-sd -B _nodmix-gw._tcp local.
+   ```
+
+   If browsing is empty or the Gateway logs show repeated ciao watchdog
+   cancellations, restore `NODMIX_DISABLE_BONJOUR=1` and use a direct or
+   Tailnet route.
+
+## Common failure modes
+
+- **Bonjour doesn't cross networks**: use Tailnet or SSH.
+- **Multicast blocked**: some Wi-Fi networks disable mDNS.
+- **Advertiser stuck in probing/announcing**: hosts with blocked multicast,
+  container bridges, WSL, or interface churn can leave the ciao advertiser in a
+  non-announced state. Nodmix retries a few times and then disables Bonjour
+  for the current Gateway process instead of restarting the advertiser forever.
+- **Docker bridge networking**: Bonjour auto-disables in detected containers.
+  Set `NODMIX_DISABLE_BONJOUR=0` only for host, macvlan, or another
+  mDNS-capable network.
+- **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`).
+
+## Enabling / disabling / configuration
+
+- macOS hosts auto-start the bundled LAN discovery plugin by default.
+- `nodmix plugins enable bonjour` enables the bundled LAN discovery plugin on hosts where it is not default-enabled.
+- `nodmix plugins disable bonjour` disables LAN multicast advertising by disabling the bundled plugin.
+- `NODMIX_DISABLE_BONJOUR=1` disables LAN multicast advertising without changing plugin config; accepted truthy values are `1`, `true`, `yes`, and `on` (legacy: `NODMIX_DISABLE_BONJOUR`).
+- `NODMIX_DISABLE_BONJOUR=0` forces LAN multicast advertising on, including inside detected containers; accepted falsy values are `0`, `false`, `no`, and `off`.
+- When the Bonjour plugin is enabled and `NODMIX_DISABLE_BONJOUR` is unset, Bonjour advertises on normal hosts and auto-disables inside detected containers.
+- `gateway.bind` in `~/.nodmix/nodmix.json` controls the Gateway bind mode.
+- `NODMIX_SSH_PORT` overrides the SSH port when `sshPort` is advertised (legacy: `NODMIX_SSH_PORT`).
+- `NODMIX_TAILNET_DNS` publishes a MagicDNS hint in TXT when mDNS full mode is enabled (legacy: `NODMIX_TAILNET_DNS`).
+- `NODMIX_CLI_PATH` overrides the advertised CLI path (legacy: `NODMIX_CLI_PATH`).
+
+## Related docs
+
+- Discovery policy and transport selection: [Discovery](/gateway/discovery)
+- Node pairing + approvals: [Gateway pairing](/gateway/pairing)