nodmix 2026.5.25

package/docs/gateway/local-models.md

@@ -0,0 +1,355 @@
+---
+summary: "Run Nodmix on local LLMs (LM Studio, vLLM, LiteLLM, custom OpenAI endpoints)"
+read_when:
+  - You want to serve models from your own GPU box
+  - You are wiring LM Studio or an OpenAI-compatible proxy
+  - You need the safest local model guidance
+title: "Local models"
+---
+
+Local models are doable. They also raise the bar on hardware, context size, and prompt-injection defense — small or aggressively quantized cards truncate context and leak safety. This page is the opinionated guide for higher-end local stacks and custom OpenAI-compatible local servers. For lowest-friction onboarding, start with [LM Studio](/providers/lmstudio) or [Ollama](/providers/ollama) and `nodmix onboard`.
+
+For local servers that should start only when a selected model needs them, see
+[Local model services](/gateway/local-model-services).
+
+## Hardware floor
+
+Aim high: **≥2 maxed-out Mac Studios or an equivalent GPU rig (~$30k+)** for a comfortable agent loop. A single **24 GB** GPU works only for lighter prompts at higher latency. Always run the **largest / full-size variant you can host**; small or heavily quantized checkpoints raise prompt-injection risk (see [Security](/gateway/security)).
+
+## Pick a backend
+
+| Backend                                              | Use when                                                                    |
+| ---------------------------------------------------- | --------------------------------------------------------------------------- |
+| [ds4](/providers/ds4)                                | Local DeepSeek V4 Flash on macOS Metal with OpenAI-compatible tool calls    |
+| [LM Studio](/providers/lmstudio)                     | First-time local setup, GUI loader, native Responses API                    |
+| LiteLLM / OAI-proxy / custom OpenAI-compatible proxy | You front another model API and need Nodmix to treat it as OpenAI         |
+| MLX / vLLM / SGLang                                  | High-throughput self-hosted serving with an OpenAI-compatible HTTP endpoint |
+| [Ollama](/providers/ollama)                          | CLI workflow, model library, hands-off systemd service                      |
+
+Use Responses API (`api: "openai-responses"`) when the backend supports it (LM Studio does). Otherwise stick to Chat Completions (`api: "openai-completions"`).
+
+<Warning>
+**WSL2 + Ollama + NVIDIA/CUDA users:** The official Ollama Linux installer enables a systemd service with `Restart=always`. On WSL2 GPU setups, autostart can reload the last model during boot and pin host memory. If your WSL2 VM repeatedly restarts after enabling Ollama, see [WSL2 crash loop](/providers/ollama#wsl2-crash-loop-repeated-reboots).
+</Warning>
+
+## Recommended: LM Studio + large local model (Responses API)
+
+Best current local stack. Load a large model in LM Studio (for example, a full-size Qwen, DeepSeek, or Llama build), enable the local server (default `http://127.0.0.1:1234`), and use Responses API to keep reasoning separate from final text.
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "lmstudio/my-local-model" },
+      models: {
+        "anthropic/claude-opus-4-6": { alias: "Opus" },
+        "lmstudio/my-local-model": { alias: "Local" },
+      },
+    },
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      lmstudio: {
+        baseUrl: "http://127.0.0.1:1234/v1",
+        apiKey: "lmstudio",
+        api: "openai-responses",
+        models: [
+          {
+            id: "my-local-model",
+            name: "Local Model",
+            reasoning: false,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 196608,
+            maxTokens: 8192,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+**Setup checklist**
+
+- Install LM Studio: [https://lmstudio.ai](https://lmstudio.ai)
+- In LM Studio, download the **largest model build available** (avoid "small"/heavily quantized variants), start the server, confirm `http://127.0.0.1:1234/v1/models` lists it.
+- Replace `my-local-model` with the actual model ID shown in LM Studio.
+- Keep the model loaded; cold-load adds startup latency.
+- Adjust `contextWindow`/`maxTokens` if your LM Studio build differs.
+- For WhatsApp, stick to Responses API so only final text is sent.
+
+Keep hosted models configured even when running local; use `models.mode: "merge"` so fallbacks stay available.
+
+### Hybrid config: hosted primary, local fallback
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: {
+        primary: "anthropic/claude-sonnet-4-6",
+        fallbacks: ["lmstudio/my-local-model", "anthropic/claude-opus-4-6"],
+      },
+      models: {
+        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
+        "lmstudio/my-local-model": { alias: "Local" },
+        "anthropic/claude-opus-4-6": { alias: "Opus" },
+      },
+    },
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      lmstudio: {
+        baseUrl: "http://127.0.0.1:1234/v1",
+        apiKey: "lmstudio",
+        api: "openai-responses",
+        models: [
+          {
+            id: "my-local-model",
+            name: "Local Model",
+            reasoning: false,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 196608,
+            maxTokens: 8192,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+### Local-first with hosted safety net
+
+Swap the primary and fallback order; keep the same providers block and `models.mode: "merge"` so you can fall back to Sonnet or Opus when the local box is down.
+
+### Regional hosting / data routing
+
+- Hosted MiniMax/Kimi/GLM variants also exist on OpenRouter with region-pinned endpoints (e.g., US-hosted). Pick the regional variant there to keep traffic in your chosen jurisdiction while still using `models.mode: "merge"` for Anthropic/OpenAI fallbacks.
+- Local-only remains the strongest privacy path; hosted regional routing is the middle ground when you need provider features but want control over data flow.
+
+## Other OpenAI-compatible local proxies
+
+MLX (`mlx_lm.server`), vLLM, SGLang, LiteLLM, OAI-proxy, or custom
+gateways work if they expose an OpenAI-style `/v1/chat/completions`
+endpoint. Use the Chat Completions adapter unless the backend explicitly
+documents `/v1/responses` support. Replace the provider block above with your
+endpoint and model ID:
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "local/my-local-model" },
+    },
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      local: {
+        baseUrl: "http://127.0.0.1:8000/v1",
+        apiKey: "sk-local",
+        api: "openai-completions",
+        timeoutSeconds: 300,
+        models: [
+          {
+            id: "my-local-model",
+            name: "Local Model",
+            reasoning: false,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 120000,
+            maxTokens: 8192,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+If `api` is omitted on a custom provider with a `baseUrl`, Nodmix defaults to
+`openai-completions`. Custom/local provider entries trust their exact configured
+`baseUrl` origin for guarded model requests, including loopback, LAN, tailnet,
+and private DNS hosts. Requests to other private origins still need
+`request.allowPrivateNetwork: true`; metadata/link-local origins remain blocked
+without explicit opt-in. Set it to `false` to opt out of exact-origin trust.
+
+The `models.providers.<id>.models[].id` value is provider-local. Do not
+include the provider prefix there. For example, an MLX server started with
+`mlx_lm.server --model mlx-community/Qwen3-30B-A3B-6bit` should use this
+catalog id and model ref:
+
+- `models.providers.mlx.models[].id: "mlx-community/Qwen3-30B-A3B-6bit"`
+- `agents.defaults.model.primary: "mlx/mlx-community/Qwen3-30B-A3B-6bit"`
+
+Set `input: ["text", "image"]` on local or proxied vision models so image
+attachments are injected into agent turns. Interactive custom-provider
+onboarding infers common vision model IDs and asks only for unknown names.
+Non-interactive onboarding uses the same inference; use `--custom-image-input`
+for unknown vision IDs or `--custom-text-input` when a known-looking model is
+text-only behind your endpoint.
+
+Keep `models.mode: "merge"` so hosted models stay available as fallbacks.
+Use `models.providers.<id>.timeoutSeconds` for slow local or remote model
+servers before raising `agents.defaults.timeoutSeconds`. The provider timeout
+applies only to model HTTP requests, including connect, headers, body streaming,
+and the total guarded-fetch abort. If the agent or run timeout is lower, raise
+that ceiling too because provider timeouts cannot extend the whole agent run.
+
+<Note>
+For custom OpenAI-compatible providers, persisting a non-secret local marker such as `apiKey: "ollama-local"` is accepted when `baseUrl` resolves to loopback, a private LAN, `.local`, or a bare hostname. Nodmix treats it as a valid local credential instead of reporting a missing key. Use a real value for any provider that accepts a public hostname.
+</Note>
+
+Behavior note for local/proxied `/v1` backends:
+
+- Nodmix treats these as proxy-style OpenAI-compatible routes, not native
+  OpenAI endpoints
+- native OpenAI-only request shaping does not apply here: no
+  `service_tier`, no Responses `store`, no OpenAI reasoning-compat payload
+  shaping, and no prompt-cache hints
+- hidden Nodmix attribution headers (`originator`, `version`, `User-Agent`)
+  are not injected on these custom proxy URLs
+
+Compatibility notes for stricter OpenAI-compatible backends:
+
+- Some servers accept only string `messages[].content` on Chat Completions, not
+  structured content-part arrays. Set
+  `models.providers.<provider>.models[].compat.requiresStringContent: true` for
+  those endpoints.
+- Some local models emit standalone bracketed tool requests as text, such as
+  `[tool_name]` followed by JSON and `[END_TOOL_REQUEST]`. Nodmix promotes
+  those into real tool calls only when the name exactly matches a registered
+  tool for the turn; otherwise the block is treated as unsupported text and is
+  hidden from user-visible replies.
+- If a model emits JSON, XML, or ReAct-style text that looks like a tool call
+  but the provider did not emit a structured invocation, Nodmix leaves it as
+  text and logs a warning with the run id, provider/model, detected pattern, and
+  tool name when available. Treat that as provider/model tool-call
+  incompatibility, not a completed tool run.
+- If tools appear as assistant text instead of running, for example raw JSON,
+  XML, ReAct syntax, or an empty `tool_calls` array in the provider response,
+  first verify the server is using a tool-call-capable chat template/parser. For
+  OpenAI-compatible Chat Completions backends whose parser works only when tool
+  use is forced, set a per-model request override instead of relying on text
+  parsing:
+
+  ```json5
+  {
+    agents: {
+      defaults: {
+        models: {
+          "local/my-local-model": {
+            params: {
+              extra_body: {
+                tool_choice: "required",
+              },
+            },
+          },
+        },
+      },
+    },
+  }
+  ```
+
+  Use this only for models/sessions where every normal turn should call a tool.
+  It overrides Nodmix's default proxy value of `tool_choice: "auto"`.
+  Replace `local/my-local-model` with the exact provider/model ref shown by
+  `nodmix models list`.
+
+  ```bash
+  nodmix config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge
+  ```
+
+- If a custom OpenAI-compatible model accepts OpenAI reasoning efforts beyond
+  the built-in profile, declare them on the model compat block. Adding `"xhigh"`
+  here makes `/think xhigh`, session pickers, Gateway validation, and `llm-task`
+  validation expose the level for that configured provider/model ref:
+
+  ```json5
+  {
+    models: {
+      providers: {
+        local: {
+          baseUrl: "http://127.0.0.1:8000/v1",
+          apiKey: "sk-local",
+          api: "openai-responses",
+          models: [
+            {
+              id: "gpt-5.4",
+              name: "GPT 5.4 via local proxy",
+              reasoning: true,
+              input: ["text"],
+              cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+              contextWindow: 196608,
+              maxTokens: 8192,
+              compat: {
+                supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
+                reasoningEffortMap: { xhigh: "xhigh" },
+              },
+            },
+          ],
+        },
+      },
+    },
+  }
+  ```
+
+## Smaller or stricter backends
+
+If the model loads cleanly but full agent turns misbehave, work top-down — confirm transport first, then narrow the surface.
+
+1. **Confirm the local model itself responds.** No tools, no agent context:
+
+   ```bash
+   nodmix infer model run --local --model <provider/model> --prompt "Reply with exactly: pong" --json
+   ```
+
+2. **Confirm Gateway routing.** Sends only the supplied prompt — skips transcript, AGENTS bootstrap, context-engine assembly, tools, and bundled MCP servers, but still exercises Gateway routing, auth, and provider selection:
+
+   ```bash
+   nodmix infer model run --gateway --model <provider/model> --prompt "Reply with exactly: pong" --json
+   ```
+
+3. **Try lean mode.** If both probes pass but real agent turns fail with malformed tool calls or oversized prompts, enable `agents.defaults.experimental.localModelLean: true`. It drops the three heaviest default tools (`browser`, `cron`, `message`) so the prompt shape is smaller and less brittle. See [Experimental Features → Local model lean mode](/concepts/experimental-features#local-model-lean-mode) for the full explanation, when to use it, and how to confirm it is on.
+
+4. **Disable tools entirely as a last resort.** If lean mode is not enough, set `models.providers.<provider>.models[].compat.supportsTools: false` for that model entry. The agent will then operate without tool calls on that model.
+
+5. **Past that, the bottleneck is upstream.** If the backend still fails only on larger Nodmix runs after lean mode and `supportsTools: false`, the remaining issue is usually upstream model or server capacity — context window, GPU memory, kv-cache eviction, or a backend bug. It is not Nodmix's transport layer at that point.
+
+## Troubleshooting
+
+- Gateway can reach the proxy? `curl http://127.0.0.1:1234/v1/models`.
+- LM Studio model unloaded? Reload; cold start is a common "hanging" cause.
+- Local server says `terminated`, `ECONNRESET`, or closes the stream mid-turn?
+  Nodmix records a low-cardinality `model.call.error.failureKind` plus the
+  Nodmix process RSS/heap snapshot in diagnostics. For LM Studio/Ollama
+  memory pressure, match that timestamp against the server log or macOS crash /
+  jetsam log to confirm whether the model server was killed.
+- Nodmix derives context-window preflight thresholds from the detected model window, or from the uncapped model window when `agents.defaults.contextTokens` lowers the effective window. It warns below 20% with an **8k** floor. Hard blocks use the 10% threshold with a **4k** floor, capped to the effective context window so oversized model metadata cannot reject an otherwise valid user cap. If you hit that preflight, raise the server/model context limit or choose a larger model.
+- Context errors? Lower `contextWindow` or raise your server limit.
+- OpenAI-compatible server returns `messages[].content ... expected a string`?
+  Add `compat.requiresStringContent: true` on that model entry.
+- OpenAI-compatible server returns `validation.keys` or says message entries only allow `role` and `content`?
+  Add `compat.strictMessageKeys: true` on that model entry.
+- Direct tiny `/v1/chat/completions` calls work, but `nodmix infer model run --local`
+  fails on Gemma or another local model? Check the provider URL, model ref, auth
+  marker, and server logs first; local `model run` does not include agent tools.
+  If local `model run` succeeds but larger agent turns fail, reduce the agent
+  tool surface with `localModelLean` or `compat.supportsTools: false`.
+- Tool calls show up as raw JSON/XML/ReAct text, or the provider returns an
+  empty `tool_calls` array? Do not add a proxy that blindly converts assistant
+  text into tool execution. Fix the server chat template/parser first. If the
+  model only works when tool use is forced, add the per-model
+  `params.extra_body.tool_choice: "required"` override above and use that model
+  entry only for sessions where a tool call is expected on every turn.
+- Safety: local models skip provider-side filters; keep agents narrow and compaction on to limit prompt injection blast radius.
+
+## Related
+
+- [Configuration reference](/gateway/configuration-reference)
+- [Model failover](/concepts/model-failover)

package/docs/gateway/logging.md

@@ -0,0 +1,149 @@
+---
+summary: "Logging surfaces, file logs, WS log styles, and console formatting"
+read_when:
+  - Changing logging output or formats
+  - Debugging CLI or gateway output
+title: "Gateway logging"
+---
+
+# Logging
+
+For a user-facing overview (CLI + Control UI + config), see [/logging](/logging).
+
+Nodmix has two log "surfaces":
+
+- **Console output** (what you see in the terminal / Debug UI).
+- **File logs** (JSON lines) written by the gateway logger.
+
+At startup, the Gateway logs the resolved default agent model together with the
+mode defaults that affect new sessions, for example:
+
+```text
+agent model: openai-codex/gpt-5.5 (thinking=medium, fast=on)
+```
+
+`thinking` comes from the default agent, model params, or global agent default;
+when it is unset, the startup summary shows `medium`. `fast` comes from the
+default agent or model `fastMode` params.
+
+## File-based logger
+
+- Default rolling log file is under `/tmp/nodmix/` (one file per day): `nodmix-YYYY-MM-DD.log`
+  - Date uses the gateway host's local timezone.
+- Active log files rotate at `logging.maxFileBytes` (default: 100 MB), keeping
+  up to five numbered archives and continuing to write a fresh active file.
+- The log file path and level can be configured via `~/.nodmix/nodmix.json`:
+  - `logging.file`
+  - `logging.level`
+
+The file format is one JSON object per line.
+
+Talk, realtime voice, and managed-room code paths use the shared file logger for
+bounded lifecycle records. These records are intended for operational debugging
+and OTLP log export; transcript text, audio payloads, turn ids, call ids, and
+provider item ids are not copied into the log record.
+
+The Control UI Logs tab tails this file via the gateway (`logs.tail`).
+CLI can do the same:
+
+```bash
+nodmix logs --follow
+```
+
+**Verbose vs. log levels**
+
+- **File logs** are controlled exclusively by `logging.level`.
+- `--verbose` only affects **console verbosity** (and WS log style); it does **not**
+  raise the file log level.
+- To capture verbose-only details in file logs, set `logging.level` to `debug` or
+  `trace`.
+- Trace logging also includes diagnostic timing summaries for selected hot paths,
+  such as plugin tool factory preparation. See
+  [/tools/plugin#slow-plugin-tool-setup](/tools/plugin#slow-plugin-tool-setup).
+
+## Console capture
+
+The CLI captures `console.log/info/warn/error/debug/trace` and writes them to file logs,
+while still printing to stdout/stderr.
+
+You can tune console verbosity independently via:
+
+- `logging.consoleLevel` (default `info`)
+- `logging.consoleStyle` (`pretty` | `compact` | `json`)
+
+## Redaction
+
+Nodmix can mask sensitive tokens before log or transcript output leaves the
+process. This logging redaction policy is applied at console, file-log, OTLP
+log-record, and session transcript text sinks, so matching secret values are
+masked before JSONL lines or messages are written to disk.
+
+- `logging.redactSensitive`: `off` | `tools` (default: `tools`)
+- `logging.redactPatterns`: array of regex strings (overrides defaults)
+  - Use raw regex strings (auto `gi`), or `/pattern/flags` if you need custom flags.
+  - Matches are masked by keeping the first 6 + last 4 chars (length >= 18), otherwise `***`.
+  - Defaults cover common key assignments, CLI flags, JSON fields, bearer headers, PEM blocks, popular token prefixes, and payment credential field names such as card number, CVC/CVV, shared payment token, and payment credential.
+
+Some safety boundaries always redact regardless of `logging.redactSensitive`.
+That includes Control UI tool-call events, `sessions_history` tool output,
+diagnostics support exports, provider error observations, exec approval command
+display, and Gateway WebSocket protocol logs. These surfaces may still use
+`logging.redactPatterns` as additional patterns, but `redactSensitive: "off"`
+does not make them emit raw secrets.
+
+## Gateway WebSocket logs
+
+The gateway prints WebSocket protocol logs in two modes:
+
+- **Normal mode (no `--verbose`)**: only "interesting" RPC results are printed:
+  - errors (`ok=false`)
+  - slow calls (default threshold: `>= 50ms`)
+  - parse errors
+- **Verbose mode (`--verbose`)**: prints all WS request/response traffic.
+
+### WS log style
+
+`nodmix gateway` supports a per-gateway style switch:
+
+- `--ws-log auto` (default): normal mode is optimized; verbose mode uses compact output
+- `--ws-log compact`: compact output (paired request/response) when verbose
+- `--ws-log full`: full per-frame output when verbose
+- `--compact`: alias for `--ws-log compact`
+
+Examples:
+
+```bash
+# optimized (only errors/slow)
+nodmix gateway
+
+# show all WS traffic (paired)
+nodmix gateway --verbose --ws-log compact
+
+# show all WS traffic (full meta)
+nodmix gateway --verbose --ws-log full
+```
+
+## Console formatting (subsystem logging)
+
+The console formatter is **TTY-aware** and prints consistent, prefixed lines.
+Subsystem loggers keep output grouped and scannable.
+
+Behavior:
+
+- **Subsystem prefixes** on every line (e.g. `[gateway]`, `[canvas]`, `[tailscale]`)
+- **Subsystem colors** (stable per subsystem) plus level coloring
+- **Color when output is a TTY or the environment looks like a rich terminal** (`TERM`/`COLORTERM`/`TERM_PROGRAM`), respects `NO_COLOR`
+- **Shortened subsystem prefixes**: drops leading `gateway/` + `channels/`, keeps last 2 segments (e.g. `whatsapp/outbound`)
+- **Sub-loggers by subsystem** (auto prefix + structured field `{ subsystem }`)
+- **`logRaw()`** for QR/UX output (no prefix, no formatting)
+- **Console styles** (e.g. `pretty | compact | json`)
+- **Console log level** separate from file log level (file keeps full detail when `logging.level` is set to `debug`/`trace`)
+- **WhatsApp message bodies** are logged at `debug` (use `--verbose` to see them)
+
+This keeps existing file logs stable while making interactive output scannable.
+
+## Related
+
+- [Logging](/logging)
+- [OpenTelemetry export](/gateway/opentelemetry)
+- [Diagnostics export](/gateway/diagnostics)

package/docs/gateway/multiple-gateways.md

@@ -0,0 +1,178 @@
+---
+summary: "Run multiple Nodmix Gateways on one host (isolation, ports, and profiles)"
+read_when:
+  - Running more than one Gateway on the same machine
+  - You need isolated config/state/ports per Gateway
+title: "Multiple gateways"
+---
+
+Most setups should use one Gateway because a single Gateway can handle multiple messaging connections and agents. If you need stronger isolation or redundancy (e.g., a rescue bot), run separate Gateways with isolated profiles/ports.
+
+## Best recommended setup
+
+For most users, the simplest rescue-bot setup is:
+
+- keep the main bot on the default profile
+- run the rescue bot on `--profile rescue`
+- use a completely separate Telegram bot for the rescue account
+- keep the rescue bot on a different base port such as `19789`
+
+This keeps the rescue bot isolated from the main bot so it can debug or apply
+config changes if the primary bot is down. Leave at least 20 ports between
+base ports so the derived browser/canvas/CDP ports never collide.
+
+## Rescue-Bot Quickstart
+
+Use this as the default path unless you have a strong reason to do something
+else:
+
+```bash
+# Rescue bot (separate Telegram bot, separate profile, port 19789)
+nodmix --profile rescue onboard
+nodmix --profile rescue gateway install --port 19789
+```
+
+If your main bot is already running, that is usually all you need.
+
+During `nodmix --profile rescue onboard`:
+
+- use the separate Telegram bot token
+- keep the `rescue` profile
+- use a base port at least 20 higher than the main bot
+- accept the default rescue workspace unless you already manage one yourself
+
+If onboarding already installed the rescue service for you, the final
+`gateway install` is not needed.
+
+## Why this works
+
+The rescue bot stays independent because it has its own:
+
+- profile/config
+- state directory
+- workspace
+- base port (plus derived ports)
+- Telegram bot token
+
+For most setups, use a completely separate Telegram bot for the rescue profile:
+
+- easy to keep operator-only
+- separate bot token and identity
+- independent from the main bot's channel/app install
+- simple DM-based recovery path when the main bot is broken
+
+## What `--profile rescue onboard` Changes
+
+`nodmix --profile rescue onboard` uses the normal onboarding flow, but it
+writes everything into a separate profile.
+
+In practice, that means the rescue bot gets its own:
+
+- config file
+- state directory
+- workspace (by default `~/.nodmix/workspace-rescue`)
+- managed service name
+
+The prompts are otherwise the same as normal onboarding.
+
+## General multi-gateway setup
+
+The rescue-bot layout above is the easiest default, but the same isolation
+pattern works for any pair or group of Gateways on one host.
+
+For a more general setup, give each extra Gateway its own named profile and its
+own base port:
+
+```bash
+# main (default profile)
+nodmix setup
+nodmix gateway --port 18789
+
+# extra gateway
+nodmix --profile ops setup
+nodmix --profile ops gateway --port 19789
+```
+
+If you want both Gateways to use named profiles, that also works:
+
+```bash
+nodmix --profile main setup
+nodmix --profile main gateway --port 18789
+
+nodmix --profile ops setup
+nodmix --profile ops gateway --port 19789
+```
+
+Services follow the same pattern:
+
+```bash
+nodmix gateway install
+nodmix --profile ops gateway install --port 19789
+```
+
+Use the rescue-bot quickstart when you want a fallback operator lane. Use the
+general profile pattern when you want multiple long-lived Gateways for
+different channels, tenants, workspaces, or operational roles.
+
+## Isolation checklist
+
+Keep these unique per Gateway instance:
+
+- `NODMIX_CONFIG_PATH` — per-instance config file
+- `NODMIX_STATE_DIR` — per-instance sessions, creds, caches
+- `agents.defaults.workspace` — per-instance workspace root
+- `gateway.port` (or `--port`) — unique per instance
+- derived browser/canvas/CDP ports
+
+If these are shared, you will hit config races and port conflicts.
+
+## Port mapping (derived)
+
+Base port = `gateway.port` (or `NODMIX_GATEWAY_PORT` / `--port`).
+
+- browser control service port = base + 2 (loopback only)
+- canvas host is served on the Gateway HTTP server (same port as `gateway.port`)
+- Browser profile CDP ports auto-allocate from `browser.controlPort + 9 .. + 108`
+
+If you override any of these in config or env, you must keep them unique per instance.
+
+## Browser/CDP notes (common footgun)
+
+- Do **not** pin `browser.cdpUrl` to the same values on multiple instances.
+- Each instance needs its own browser control port and CDP range (derived from its gateway port).
+- If you need explicit CDP ports, set `browser.profiles.<name>.cdpPort` per instance.
+- Remote Chrome: use `browser.profiles.<name>.cdpUrl` (per profile, per instance).
+
+## Manual env example
+
+```bash
+NODMIX_CONFIG_PATH=~/.nodmix/main.json \
+NODMIX_STATE_DIR=~/.nodmix \
+nodmix gateway --port 18789
+
+NODMIX_CONFIG_PATH=~/.nodmix/rescue.json \
+NODMIX_STATE_DIR=~/.nodmix-rescue \
+nodmix gateway --port 19789
+```
+
+## Quick checks
+
+```bash
+nodmix gateway status --deep
+nodmix --profile rescue gateway status --deep
+nodmix --profile rescue gateway probe
+nodmix status
+nodmix --profile rescue status
+nodmix --profile rescue browser status
+```
+
+Interpretation:
+
+- `gateway status --deep` helps catch stale launchd/systemd/schtasks services from older installs.
+- `gateway probe` warning text such as `multiple reachable gateways detected` is expected only when you intentionally run more than one isolated gateway.
+
+## Related
+
+- [Gateway runbook](/gateway)
+- [Gateway lock](/gateway/gateway-lock)
+- [Configuration](/gateway/configuration)