fengming 0.3.9 → 0.3.11

package/docs/gateway/local-models.md

@@ -1,355 +0,0 @@
----
-summary: "Run FengMing 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 `fengming 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 FengMing 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`, FengMing 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. FengMing 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:
-
-- FengMing 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 FengMing 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]`. FengMing 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, FengMing 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 FengMing's default proxy value of `tool_choice: "auto"`.
-  Replace `local/my-local-model` with the exact provider/model ref shown by
-  `fengming models list`.
-
-  ```bash
-  fengming 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
-   fengming 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
-   fengming 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 FengMing 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 FengMing'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?
-  FengMing records a low-cardinality `model.call.error.failureKind` plus the
-  FengMing 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.
-- FengMing 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 `fengming 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

@@ -1,149 +0,0 @@
----
-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).
-
-FengMing 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/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/fengming/` (one file per day): `fengming-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 `~/.fengming/fengming.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
-fengming 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
-
-FengMing 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
-
-`fengming 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)
-fengming gateway
-
-# show all WS traffic (paired)
-fengming gateway --verbose --ws-log compact
-
-# show all WS traffic (full meta)
-fengming 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

@@ -1,178 +0,0 @@
----
-summary: "Run multiple FengMing 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)
-fengming --profile rescue onboard
-fengming --profile rescue gateway install --port 19789
-```
-
-If your main bot is already running, that is usually all you need.
-
-During `fengming --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
-
-`fengming --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 `~/.fengming/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)
-fengming setup
-fengming gateway --port 18789
-
-# extra gateway
-fengming --profile ops setup
-fengming --profile ops gateway --port 19789
-```
-
-If you want both Gateways to use named profiles, that also works:
-
-```bash
-fengming --profile main setup
-fengming --profile main gateway --port 18789
-
-fengming --profile ops setup
-fengming --profile ops gateway --port 19789
-```
-
-Services follow the same pattern:
-
-```bash
-fengming gateway install
-fengming --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:
-
-- `FENGMING_CONFIG_PATH` — per-instance config file
-- `FENGMING_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 `FENGMING_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
-FENGMING_CONFIG_PATH=~/.fengming/main.json \
-FENGMING_STATE_DIR=~/.fengming \
-fengming gateway --port 18789
-
-FENGMING_CONFIG_PATH=~/.fengming/rescue.json \
-FENGMING_STATE_DIR=~/.fengming-rescue \
-fengming gateway --port 19789
-```
-
-## Quick checks
-
-```bash
-fengming gateway status --deep
-fengming --profile rescue gateway status --deep
-fengming --profile rescue gateway probe
-fengming status
-fengming --profile rescue status
-fengming --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)