better-dsh 0.2.4-a → 0.2.4-b

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/multi-profile-gateways.md

@@ -1,1062 +0,0 @@
----
-sidebar_position: 4
----
-
-# Running Many Gateways at Once
-
-Operate multiple [profiles](./profiles.md) — each with its own bot tokens,
-sessions, and memory — as managed services on a single machine. This page
-covers the operational concerns: starting them all together, viewing logs
-across profiles, preventing the host from sleeping, and recovering from common
-launchd/systemd quirks.
-
-If you only run one Hermes agent, you don't need this page — see
-[Profiles](./profiles.md) for the basics. And if your instances live on
-*different* machines that one desktop app should reach simultaneously, see
-[Connecting Desktop to Many Hermes Instances](./multi-connection-desktop.md).
-
-## When to use this
-
-You want this setup when you have two or more Hermes agents that should all
-be online at the same time. Common reasons:
-
-- A personal assistant on one Telegram bot and a coding agent on another
-- One agent per family member or one per Slack workspace
-- Sandbox + production instances of the same configuration
-- A research agent + a writing agent + a cron-driven bot — each with isolated
-  memory and skills
-
-Every profile already gets its own per-platform supervisor entry: a LaunchAgent
-(`ai.hermes.gateway-<name>.plist`), a systemd user service
-(`hermes-gateway-<name>.service`), a systemd **system** service when installed with
-`sudo hermes gateway install --system` (runs as the invoking user via `User=`), a
-Windows Scheduled Task, or an s6/Docker service — and the Desktop app spawns its own
-per-profile `hermes serve` backend. This guide adds the patterns for managing them
-collectively.
-
-## Quick start
-
-```bash
-# Create profiles (once)
-hermes profile create coder
-hermes profile create personal-bot
-hermes profile create research
-
-# Configure each
-coder setup
-personal-bot setup
-research setup
-
-# Install each gateway as a managed service
-coder gateway install
-personal-bot gateway install
-research gateway install
-
-# Start them all
-coder gateway start
-personal-bot gateway start
-research gateway start
-```
-
-That's it — three independent agents, each on its own process, restarting
-automatically on crash and on user login.
-
-## Alternative: one gateway for all profiles (multiplexing)
-
-The model above runs **one process per profile**. The alternative is a
-**single multiplexing gateway**: the default profile's gateway becomes the sole
-inbound process and serves messages for *every* profile on the box.
-
-Multiplexing is **on by default** (`gateway.multiplex_profiles` defaults to
-`true`), with one safety rule: an *unset* flag is a request the default gateway
-settles at boot, never a verdict. Each start it runs the same preflight as
-[`hermes gateway migrate --multiplex`](#migrating-from-per-profile-gateways) and
-multiplexes only when the fold would have been safe — the default profile, two
-or more profiles, no secondary still running its own gateway (live process or
-installed service), no duplicate bot credential, no port-binding platform
-without a `/p/<profile>/` ingress, and a host the migration understands (not an
-s6 container or Windows Scheduled Tasks). Otherwise it comes up exactly as
-before — serving the default profile only — and logs the blocker plus the
-`hermes gateway migrate --multiplex` one-liner. Nothing is changed on disk.
-
-An **explicit** value is never second-guessed:
-
-- `gateway.multiplex_profiles: true` (what the migration writes) multiplexes
-  regardless of the preflight — you, or the migration, made the call.
-- `gateway.multiplex_profiles: false` (what `--standalone` restores) keeps
-  per-profile gateways for good. When it's off, nothing on this page changes —
-  every behavior below is inert.
-- `GATEWAY_MULTIPLEX_PROFILES` in the process environment overrides both.
-
-Other processes (`hermes -p <name> gateway start`, the dashboard, `hermes gateway
-migrate`) never guess how an unset flag was settled: they read the running
-default gateway's `served_profiles` record, and fall back to the explicit flag
-only when no gateway runs.
-
-### When to prefer multiplexing
-
-- A container/VPS deployment where N supervisor units, N ports, and N PID files
-  are a burden.
-- Many low-traffic profiles that don't each justify a full process.
-- You want a single thing to start, monitor, and restart.
-
-Stick with one-process-per-profile when you want hard process-level isolation
-between profiles (separate memory footprints, independent crash domains, the
-ability to restart one profile without touching the others).
-
-### Pinning the flag
-
-With the flag unset, the default gateway decides at each boot (above). To pin
-it, set it on the **default profile** (it owns the multiplexer) and restart its
-gateway — `true` forces multiplexing even where the boot preflight would have
-held back, `false` opts out durably:
-
-```bash
-hermes config set gateway.multiplex_profiles true    # or false
-hermes gateway restart
-```
-
-Equivalently, in the default profile's `~/.hermes/config.yaml`:
-
-```yaml
-gateway:
-  multiplex_profiles: true
-```
-
-(The flag is also accepted as a top-level `multiplex_profiles: true` for
-convenience.) When multiplexing, the default gateway enumerates every profile,
-brings up each profile's enabled platforms under that profile's own
-credentials, and routes each inbound message to the profile it belongs to. Each
-turn resolves the routed profile's config, skills, memory, SOUL, **and provider
-keys** — credentials are never shared across profiles.
-
-You do **not** run `hermes gateway start` for the secondary profiles — the
-default gateway serves them. See the contract changes below.
-
-### What changes when multiplexing is on
-
-Enabling the flag changes how a few things behave. All of these revert the
-moment the flag is off.
-
-#### 1. Secondary profiles must not start their own gateway
-
-With a multiplexer running, a named-profile `hermes gateway run`, `start`,
-`install` or `restart` is a **hard error** (exit code 78), pointing you back at
-the multiplexer:
-
-```
-The default gateway is running as a profile multiplexer and already serves
-profile 'coder'. ...
-```
-
-The refusal happens in the CLI before any service manager is touched, so a served
-profile never ends up with a permanently failed systemd unit or a launchd respawn
-loop. `hermes -p coder gateway stop` refuses the same way (exit 78) when coder has no
-gateway of its own — there is nothing to stop but the multiplexer, which
-`hermes gateway stop` on the default profile takes down for every served profile.
-The dashboard and Desktop app follow the CLI: for a served profile the "Start" and
-"Stop" gateway actions answer `409` with the same explanation (rendered as an inline
-notice on the System page), and "Restart" restarts the multiplexer (the process that
-actually serves the profile) instead of spawning a `-p coder gateway restart` that
-could only fail. Because that restart reconnects every bot on the device, both apps
-first ask *"Restart the shared gateway? All bots on this device reconnect: default,
-coder, research"* (the list is the running gateway's `served_profiles`) and report
-*"Shared gateway restarted (3 bots)"* when it completes. A standalone profile keeps
-the plain restart. `/api/status?profile=coder` carries the same list as
-`gateway_shared_with` (null for a standalone gateway).
-"Served" is read from the running gateway's own record (`served_profiles` in the
-default home's `gateway_state.json`), so it stays correct when the multiplexer was
-enabled only through `GATEWAY_MULTIPLEX_PROFILES` in the default profile's
-environment, or when profiles were added after the gateway started.
-
-The setup flows follow the same rule: `hermes -p coder setup gateway`, `hermes -p coder setup`,
-`hermes -p coder gateway setup` and `hermes -p coder import` configure the profile's bots but
-skip the "install the gateway background service" step for a served profile, printing
-*"Profile 'coder' is already served by the default multiplexer"* instead of registering a
-stray unit or plist that could only sit dead. Add the bot token and the running multiplexer
-picks it up.
-
-The multiplexer is the single inbound process; a second profile gateway would
-double-bind that profile's platforms. Pass `--force` (accepted by `run`, `start`,
-`install` and `restart`) only if you deliberately want a separate process for that
-profile (not recommended while the multiplexer is running). The cross-profile
-lifecycle wrapper script earlier on this page is therefore **not** used in
-multiplex mode — you only manage the default gateway.
-
-#### 2. HTTP-inbound platforms are reached via a `/p/<profile>/` URL prefix
-
-HTTP-inbound traffic for a secondary profile arrives on the default profile's
-**one** listener under a profile prefix, **not** a second port:
-
-```
-# default profile
-POST http://host:8644/webhooks/<route>
-# the "coder" profile, same listener
-POST http://host:8644/p/coder/webhooks/<route>
-```
-
-An unknown or unconfigured profile in the prefix returns `404`. The shared
-listener is the default profile's `api_server` port (or its `webhook` port when
-no API server is enabled); it serves three kinds of profile-prefixed paths:
-
-- **`api_server` and `webhook` are mirrored**, never duplicated. `/p/coder/v1/...`
-  and `/p/coder/webhooks/<route>` are answered by the default profile's own
-  adapter under coder's scope. A secondary must therefore **not** enable
-  `api_server` or `webhook` itself (the dashboard refuses with `409`; an
-  `API_SERVER_KEY` or `WEBHOOK_ENABLED` in the secondary's `.env` wires the
-  credential without starting a listener).
-- **Every other inbound-port platform runs in shared-listener mode.** A
-  secondary that configures Twilio SMS, LINE, Teams, BlueBubbles, Microsoft
-  Graph, WhatsApp Cloud, WeCom callback or Feishu webhook mode gets its **own**
-  adapter instance built without a port; the default listener forwards
-  `/p/<profile>/<the adapter's usual path>` to it. See
-  [Inbound-port platforms under the multiplexer](#inbound-port-platforms-under-the-multiplexer).
-- **WhatsApp (bridge) and Relay are shared ingress owned by the default profile.**
-  The multiplexer never starts them for a secondary: `WHATSAPP_ENABLED=true` in
-  `profiles/work/.env` does nothing on its own. Enable and configure them on the
-  default profile (their inbound is routed to profiles via `profile_routes`), or
-  disable them in the secondary. The gateway logs one INFO line per skipped
-  secondary platform, and if **no** profile runs it a WARNING says the platform
-  is not being served; `hermes gateway status --profile work` shows
-  `whatsapp: not served under multiplex (shared ingress owned by default)`.
-
-Authentication follows the profile named in the URL. Unprefixed endpoints keep
-using the default listener's existing credentials.
-
-- `/p/coder/...` API-server requests must use `API_SERVER_KEY` from
-  `~/.hermes/profiles/coder/.env`; the default listener key is rejected. Under
-  the multiplexer that key only authenticates the prefix — it does not turn on a
-  second `api_server` listener in the secondary profile, so you do not need to
-  pin `platforms.api_server.enabled: false` in the secondary's `config.yaml`.
-- A webhook route that targets `coder` must declare `profile: coder` beside
-  its existing route-specific `secret` in the default profile's
-  `config.yaml`. That secret is then accepted only at
-  `/p/coder/webhooks/<route>` and is rejected on every other profile prefix.
-- Webhook routes without `profile` remain default-profile routes and are not
-  reachable through a named profile prefix. Dynamic subscriptions bind the same
-  way: `hermes webhook subscribe <name> --route-profile coder` writes
-  `profile: coder` into the default gateway's `webhook_subscriptions.json` and
-  prints the `/p/coder/webhooks/<name>` URL (`hermes webhook ls` shows the
-  binding). Use `--route-profile`, not the global `-p coder`: `-p` would write
-  the subscription into coder's own subscriptions file, which the default
-  gateway's webhook adapter never reads.
-- Delivery follows the same binding. A `profile: coder` route's reply (or
-  `deliver_only` message) goes out through **coder's** adapter for the
-  `deliver` platform, falls back to **coder's** home channel when
-  `deliver_extra.chat_id` is unset, and a `github_comment` delivery runs `gh`
-  with `GH_TOKEN` / `GITHUB_TOKEN` from `profiles/coder/.env`. If coder has no
-  adapter for that platform the delivery fails (502) rather than posting as
-  another profile's bot; a default route likewise never borrows a platform that
-  is enabled only on a secondary profile.
-- `/p/coder/api/platforms/<platform>/events` callbacks are verified and
-  dispatched by coder's adapter; when coder has none the callback is a 503.
-
-Named API requests fail closed when the target profile has no
-`API_SERVER_KEY`. Security configuration errors remain fatal: for example, an
-`open` own-policy platform without `GATEWAY_ALLOW_ALL_USERS` or its
-platform-specific allow-all opt-in still aborts gateway startup rather than
-silently dropping the unsafe profile.
-
-#### Inbound-port platforms under the multiplexer
-
-A standalone `hermes -p coder gateway run` binds coder's Twilio, LINE, Teams,
-… webhook servers on their own ports. Under the multiplexer those adapters are
-still coder's — same credentials from `profiles/coder/.env`, same
-`config.yaml`, replies sent through coder's channel — but they bind **no port**.
-The default profile's shared listener forwards `/p/coder/<path>` to them, where
-`<path>` is exactly the path the adapter would serve standalone. The request is
-verified by **coder's** adapter with **coder's** secret (Twilio auth token, LINE
-channel secret, Teams app credentials, BlueBubbles password, …) and runs under
-coder's runtime scope; the default profile's own `/path` is untouched, and a
-profile that has no adapter for a path gets `404`, never another profile's bot.
-
-| Platform | Secondary profile's callback URL on the shared listener | Verified with the named profile's |
-|---|---|---|
-| Twilio SMS (`sms`) | `https://<host>/p/<profile>/webhooks/twilio` | `TWILIO_AUTH_TOKEN` signature (`SMS_WEBHOOK_URL` must be this URL) |
-| LINE (`line`) | `https://<host>/p/<profile>/line/webhook` (media: `/p/<profile>/line/media/...`) | `LINE_CHANNEL_SECRET` |
-| Microsoft Teams (`teams`) | `https://<host>/p/<profile>/api/messages` | Bot Framework token for `TEAMS_CLIENT_ID` |
-| BlueBubbles (`bluebubbles`) | `http://<host>/p/<profile>/bluebubbles-webhook` (registered with the server automatically) | `BLUEBUBBLES_PASSWORD` |
-| Microsoft Graph (`msgraph_webhook`) | `https://<host>/p/<profile>/msgraph/webhook` | `extra.client_state` |
-| WhatsApp Cloud (`whatsapp_cloud`) | `https://<host>/p/<profile>/whatsapp/webhook` | `WHATSAPP_CLOUD_APP_SECRET` / verify token |
-| WeCom callback (`wecom_callback`) | `https://<host>/p/<profile>/wecom/callback` | the app's callback token / AES key |
-| Feishu webhook mode (`feishu`) | `https://<host>/p/<profile>/feishu/webhook` | `FEISHU_VERIFICATION_TOKEN` / `FEISHU_ENCRYPT_KEY` |
-
-`<host>` is the public hostname (tunnel, reverse proxy) in front of the default
-profile's listener; a custom `webhook_path` in the profile's config moves the
-path after `/p/<profile>` accordingly. The gateway logs the exact URL at
-startup:
-
-```
-[sms] profile 'coder' is served on the default profile's shared listener:
-http://127.0.0.1:8642/p/coder/webhooks/twilio (point the vendor's callback URL at this path ...)
-```
-
-and every status surface repeats it, so you know what to paste into the vendor
-console:
-
-```
-$ hermes -p coder gateway status
-✓ Gateway is running via the default-profile multiplexer
-  Manage it from the default profile: hermes gateway status
-
-Inbound callback URLs on the shared listener:
-  line: http://127.0.0.1:8642/p/coder/line/webhook
-  sms: http://127.0.0.1:8642/p/coder/webhooks/twilio
-```
-
-`hermes gateway status` and `hermes status` on the default profile list the same
-URLs per served profile, and the dashboard's Channels page and the Desktop
-Messaging page show them as each platform's `ingress_url` when viewing that
-profile. The default's own `api_server` and `webhook` are reported the same way
-for a served profile — as **connected** with `ingress_url`
-`http://127.0.0.1:8642/p/coder/v1` (respectively `.../p/coder/webhooks/<route>`) —
-since the profile has no adapter of its own for them; it is the default's listener
-answering under the `/p/coder/` prefix. A per-profile
-`SMS_WEBHOOK_PORT`, `LINE_PORT`, `TEAMS_PORT`, … in a secondary's `.env` is
-ignored under the multiplexer (nothing binds); it applies again the moment that
-profile runs its own standalone gateway.
-
-#### 3. Per-credential platforms still need their own token per profile
-
-Polling/connection platforms (Telegram, Discord, Slack, Matrix, Signal, …) work
-fine multiplexed, but each profile that enables one must supply its **own** bot
-token — the same token cannot be polled by two profiles at once. If two profiles
-configure the same `(platform, token)`, the gateway logs an error naming both
-profiles and parks the **duplicate** adapter (it shows as `fatal /
-duplicate_credential` in runtime status) while the first claimant and every
-other profile keep running — the gateway itself does not exit. The default
-profile's adapters connect first and claim their credentials, so the parked
-adapter is always the secondary's (see
-[Token-conflict safety](#token-conflict-safety) — the rule is unchanged, it's
-just enforced inside the one process now).
-
-#### 4. Session keys are namespaced by profile
-
-Each profile's sessions live under an `agent:<profile>:…` namespace so two
-profiles on the same platform/chat never collide in the shared session store.
-The **default** profile keeps the historical `agent:main:…` namespace
-byte-for-byte, so existing default-profile sessions are unaffected — no
-migration, no orphaned history. Every gateway path that reads a key back —
-delegation completions after a restart, shutdown notices, a per-user-thread
-`/stop` of a sibling's run, `/undo`, QQ approval buttons — accepts the
-`agent:<profile>:…` shape too, so secondary profiles get the same behaviour
-as the default one. The one profile name that would collide with the default's
-namespace, a profile literally called `main`, is keyed `agent:main~:…` so it
-keeps its own sessions and its own `profiles/main/state.db`.
-
-Each profile's rows land in **its own** `state.db`: a named profile's under
-`profiles/<name>/state.db`, the default profile's under the launch home — even
-when the write happens inside another profile's routed turn or background tick.
-The Desktop/TUI backend's own store is likewise pinned to the home it launched
-under, and a Bot Chat's side agents (`prompt.background`) persist next to their
-parent conversation.
-
-#### 5. One PID/lock and one status surface
-
-There is a single process-level PID and lock (the multiplexer, under the default
-home). `hermes status` on the default profile reports the multiplexer and lists
-the profiles it serves (`Serves: coder, research`); `hermes -p coder status`,
-`hermes -p coder gateway status` and `hermes -p coder cron status` all report
-"running via the default-profile multiplexer" instead of "stopped", and the
-dashboard's `/api/status?profile=coder` / Channels page report the multiplexer as
-coder's running gateway (with coder's own adapters as its platforms). The single
-`gateway_state.json` lives under the default home: secondary adapters appear
-there as `<profile>:<platform>` entries beside `served_profiles`; nothing is
-written under a secondary profile's home.
-
-#### What does **not** change
-
-Per-profile `.env` credential isolation is preserved and, if anything,
-stricter: a profile's keys are resolved from its own scope and are never unioned
-into a shared environment. Subprocesses like MCP servers and Kanban workers only
-ever see their own profile's secrets — including credentials injected by an
-external secret source (1Password, Bitwarden, …): a stdio MCP server started for
-profile B receives B's value for such a name, or nothing if B has none, never the
-default profile's. MCP servers are connected **per profile**: two profiles that
-both name a server `github` with their own token get two connections and each
-sees only its own tools; profiles whose `mcp_servers` entry is identical (same
-route *and* credentials, including mTLS `client_cert`/`client_key`) share one
-connection, and an owner's `/reload-mcp`
-re-registers the sharing profiles' tools without them reloading. `auth: oauth`
-servers are never shared across profiles: each profile holds its own token under
-its own `mcp-tokens/` and opens its own connection. Trust policy stays per
-profile: a `trust: untrusted` profile sharing a `trust: full` profile's
-connection is still asked before every write-capable call, and
-`supports_parallel_tool_calls` applies only to the profile that set it. Terminal settings
-(`terminal.backend`, `terminal.cwd`, `terminal.docker_volumes`,
-`terminal.docker_shared_container_key`, SSH targets, …) are likewise resolved
-per profile on every routed turn: a profile that omits a terminal key gets the
-documented default, never the launch profile's value, and a profile whose
-`config.yaml`/`.env` cannot be parsed has terminal execution refused rather than
-run under another profile's sandbox policy. The media-delivery credential
-guard (the denylist behind `MEDIA:` attachments — `.env`, `auth.json`,
-`config.yaml`, `state.db`, session transcripts, OAuth token stores) covers every
-profile under `profiles/`, so no profile's turn can attach another profile's
-secrets or chat history to a reply. Authorization is per profile too:
-`GATEWAY_ALLOW_ALL_USERS`, `GATEWAY_ALLOWED_USERS` and every platform allowlist
-or allow-all opt-in are read from the owning profile's `.env` — the default
-profile opting into open access never opens a secondary profile's bot, and a
-secondary that opts in only in its own `.env` is honored. The same holds for
-per-bot behaviour written in a profile's `config.yaml` (`require_mention`,
-`mention_patterns`, `allow_bots`, `reactions`, `auto_thread`, `dm_policy`,
-`ignored_channels`, Matrix `session_scope`, …): a secondary profile's YAML never
-lands in the shared process environment, so it cannot become the default
-profile's policy, and the default profile's YAML never governs a secondary
-bot. The `terminal.env_passthrough` allowlist, the Yuanbao auto-designated
-home channel, and the write guards protecting each profile's own `config.yaml`
-are resolved per profile as well. Kanban, profile-scoped skills/memory/SOUL, and
-model routing all behave per-profile exactly as they do with separate gateways.
-
-Outbound identity is per profile too. A turn running for profile `P` that calls
-the `send_message` tool (send, react, media) posts through `P`'s own bot;
-so do the "Gateway shutting down/restarted" and `/update` notices for `P`'s
-sessions, `/loop` wakeups set from `P`'s chats, and the Discord
-unauthorized-slash operator alert of `P`'s Discord bot (to `P`'s home
-channel). If `P` has no connected bot for that platform the send fails with a
-clear error — it never falls back to the default profile's bot.
-
-Tool and memory-provider credentials follow the same rule. Hosted OCR
-(`FIRECRAWL_API_KEY`), Modal / Browser Use cloud gates, the mem0 OSS OpenAI
-key, xAI video, and every memory-provider identity (`MEM0_USER_ID`,
-`SUPERMEMORY_CONTAINER_TAG`, `RETAINDB_PROJECT`, `OPENVIKING_ACCOUNT/USER`,
-`HINDSIGHT_BANK_ID`, `HERMES_HONCHO_HOST`) are read from the routed profile's
-`.env`, so a secondary profile's memories land in **its** account/bank/project
-(or the provider's per-profile default), never the default profile's. Custom
-endpoints travel with their keys — `OPENAI_BASE_URL`, `XAI_BASE_URL`,
-`NOUS_INFERENCE_BASE_URL`, `GATEWAY_PROXY_URL`, Firecrawl / Browserbase /
-RetainDB / Supermemory / Honcho / Hindsight URLs — so a profile's key is never
-sent to another profile's proxy or self-hosted server. `WEIXIN_HOME_CHANNEL`,
-`HERMES_LANGUAGE` and `display.language`, and `hooks.outbound[].secret_env` are
-likewise per profile, and end-of-session memory extraction for an evicted
-secondary session runs under that profile's scope.
-
-Per-turn runtime settings follow the routed profile as well: `agent.max_turns`,
-`fallback_providers`, `file_read_max_chars`, `tool_output.*`, `browser.*`
-timeouts, `timezone` (including the `TZ` handed to `execute_code` sandboxes),
-the media-delivery policy (`gateway.strict`, `media_delivery_allow_dirs`,
-`trust_recent_files*`) and the Nous `auth.json` used for auxiliary calls are all
-read from the profile serving the turn, never from the profile the gateway was
-launched under. The same holds for per-profile state files (`processes.json`,
-`checkpoints/`, sandbox snapshot stores, Feishu comment rules/pairing) and for
-gateway hooks: each profile's `hooks/` directory is loaded on its own and fires
-only for that profile's events. Shell hooks run with the routed profile's
-`HERMES_HOME`, without the default profile's secrets in their environment, and
-their stdin payload carries a `profile` field naming the profile that fired them.
-
-#### What is isolated per profile
-
-A quick reference for what a multiplexed turn resolves from **its own**
-profile and never shares with the default or any sibling:
-
-| Concern | Resolved from | Behaviour when the profile lacks it |
-|---|---|---|
-| Provider keys, bot tokens, `${VAR}` refs in `config.yaml` | The profile's own `.env` (its secret scope) | Unresolved / no adapter — never the default profile's value |
-| Authorization (`GATEWAY_ALLOW_ALL_USERS`, `GATEWAY_ALLOWED_USERS`, per-platform allowlists and allow-all opt-ins) | The owning profile's `.env` and `config.yaml` | Closed — a default-profile opt-in never opens a secondary's bot |
-| HTTP endpoints (`/p/<profile>/api/...`, `/p/<profile>/webhooks/...`, platform event callbacks) | The named profile's `API_SERVER_KEY`, `profile:`-bound webhook routes, and its own adapter | `401`/`404`; delivery without an adapter is `502`/`503`, never another profile's bot |
-| Inbound-port platforms (`/p/<profile>/webhooks/twilio`, `/p/<profile>/line/webhook`, `/p/<profile>/api/messages`, …) | The named profile's own adapter and its secret (Twilio auth token, LINE channel secret, Teams app, BlueBubbles password, …); replies leave through that adapter | `401`/`403` on a wrong secret, `404` when the profile has no such adapter — never the default profile's adapter |
-| Adapter settings (`*_REQUIRE_MENTION`, `*_REACTIONS`, `*_ALLOW_BOTS`, `*_PROXY`, Discord `allow_mentions`, Matrix `allowed_users` / `ignore_user_patterns`, webhook host/port/URL, Matrix thread/session/E2EE policy, Discord backfill/attachment caps, Buzz reply mode, A2A agent card / public URL, WhatsApp bridge policy, Yuanbao home channel) | The owning profile, in this order: explicit `.env` value → its `config.yaml` → the adapter's default | The adapter's documented default — never the default profile's setting. Single-profile installs keep env-over-YAML exactly as each platform page documents |
-| `MEDIA:` attachment denylist | Every home under `profiles/` plus the default home, enumerated at check time | A turn can never attach another profile's `.env`, `auth.json`, `state.db`, sessions or token stores |
-| stdio MCP child environment | Safe baseline + the profile's scoped values for secret-source names + the server's own `env:` | A name the profile lacks is absent from the child — no default-profile fallthrough |
-| Outbound egress (`send_message`, shutdown/restart/`/update` notices, `/loop` wakeups, `profile:`-bound webhook delivery, `github_comment` tokens) | The profile's own connected adapter and `.env` | Clear failure; never posts through the default profile's bot |
-| Session namespace | `agent:<profile>:…` (default keeps `agent:main:…`) | Two profiles on the same chat never share history |
-| Logs | `agent.log` / `errors.log` / `gateway.log` under the profile's own home | — |
-| Terminal sandbox settings (`terminal.*`, SSH targets) | The profile's `config.yaml` | Documented default; unparsable config → execution refused |
-| Working directory of a turn (unset `terminal.cwd`) | Same rule as a standalone gateway: `$HOME` for the local backend, sandbox default otherwise | Never the directory the multiplexer process was launched from |
-| Command approvals (`command_allowlist`, "always" choices) | The profile's own `config.yaml` | A default-profile "always" never pre-approves a secondary's command; a secondary's choice is saved to its own config |
-| Sandbox credential-file mounts (`terminal.credential_files`), `security.redact_secrets`, `browser.*` engine/headed flags, `lsp.*`, auxiliary-provider health marks, `logs/mcp-stderr.log` | The profile's own `config.yaml` / `.env` | Documented default — never the launch profile's cached value |
-| Cloud-SDK credential clients (Bedrock boto3 clients + model discovery, Azure Entra credential), credential-fetched catalogs (DeepInfra, Copilot context limits, Nous reasoning caps, Ramp Router efforts, xAI / OpenRouter image models, custom-endpoint `/models`), Camofox VNC address, computer-use aux-vision routing, skill-sync push, remote-backend probe text, learned image token costs, `display.skin`, guest-mint back-off, banner skills, Yuanbao "active" adapter, Langfuse client | The profile's own `.env` / `config.yaml` / `<home>/cache` | Documented default — never the launch profile's cached value or its credentials |
-| Session-search knobs (`sessions.cjk_fts`, `sessions.search_slow_ms`) | The profile's `config.yaml` | Documented default — never the default profile's bridged value |
-| Platform proxies (`TELEGRAM_PROXY`, `DISCORD_PROXY`, `HTTPS_PROXY`, …) | The profile's own `.env` | Direct connection — never the default profile's proxy |
-| MCP discovery in the Desktop/dashboard backend | Once per served profile home | A profile selected after another has already built an agent still discovers its own `mcp_servers` |
-| MCP connections in the Desktop/dashboard backend and the per-profile cron ticker | Keyed per served profile even with `gateway.multiplex_profiles` off — same rule as the multiplexer | A same-named `mcp_servers` entry with other credentials is its own connection; a served profile never calls a server as another profile |
-| Dashboard actions (`hermes -p <name> …` spawned by the Desktop/dashboard) | A scrubbed child env pinned to that profile's `HERMES_HOME` | The child loads its own `.env`; the dashboard profile's tokens and ports are not inherited |
-| Every child that acts for a served profile (slash worker, Bot Chat delivery, A2A forward, `key_cmd` helper, browser driver) | That profile's own `.env` + secret sources over a credential-scrubbed base — with or without `gateway.multiplex_profiles` (the Desktop/dashboard `?profile=` route counts) | Absent from the child — a key that reached the launch process only through systemd / Compose / the shell is never inherited by another profile's child |
-| The launch (default) profile's own credentials in a `hermes serve` / dashboard process that also serves another profile | Its `.env` + secret sources over the process env **frozen the moment the first other profile is served**; not re-read afterwards | A credential rotated only in the process env (`systemctl set-environment`, a refreshed `op run` wrapper that did not re-exec) is not picked up until the process restarts — put rotating keys in `.env` or a secret source, or restart after rotating |
-| Cron `.env` tuning (`HERMES_CRON_TIMEOUT`, `HERMES_MODEL` fallback, `HERMES_CRON_MAX_PARALLEL`, prefill file), worker / Bot Chat child env | The profile's own `.env`; children never inherit the default profile's `.env` settings or bridged `TERMINAL_*` policy | Cron defaults / model refusal, exactly as a standalone `hermes -p <name> gateway run` |
-| Kanban workers and notifications for a profile's tasks | The assignee's `.env` + `config.yaml` (toolset pin, terminal backend, media policy, display language) | — |
-| `/loop` ticks, `background_process_notifications` gate, `notice_delivery`, background-process checkpoint recovery | The owning profile's `state.db` / `config.yaml` / `processes.json` | — |
-
-What is **shared** by design: the process, its PID/lock and `gateway_state.json`
-(default home), the one HTTP listener, and the `profile_routes` table (declared
-on the default profile).
-
-### Which profiles are served
-
-`gateway.multiplex_profiles: true` serves the default profile plus **every**
-live named profile under `profiles/` — there is no per-profile opt-out list.
-(The former `gateway.multiplex_profile_allowlist` key is retired; a config
-migration removes it from `config.yaml`, and a profile you do not want served is
-archived or deleted instead — `hermes profile delete <name>`, or move the
-directory out of `profiles/`.) Deleted profiles leave a tombstone and are never
-enumerated; a profile whose directory is gone is never recreated by a served
-turn, the cron ticker or log routing.
-
-The served set controls `/p/<profile>/` API and webhook prefixes, runtime
-status, profile-route eligibility, and which profiles the in-process cron
-scheduler ticks (the Desktop backend's ticker re-enumerates the same set on
-every cycle — a profile created or deleted while Desktop runs joins or leaves
-the ticked set without a restart — and stands down for any profile a running
-multiplexer or its own gateway already serves). A
-multiplexer started as `hermes -p <name> gateway run` always ticks its own
-profile's cron store as well.
-
-The served set is **live**. A profile created while the multiplexer is running
-(`hermes profile create`, the dashboard, Desktop or the TUI) is served at once:
-the creator pings the multiplexer over its control socket, and the multiplexer
-also rescans `profiles/` every 30 seconds as a safety net. The new profile's
-adapters are built the moment its `config.yaml`/`.env` carries a bot token
-(creators usually create first, then add the token), `served_profiles` in the
-default profile's `gateway_state.json` is updated, and `hermes -p <name> gateway
-status` reports it as served — no restart, and the other profiles' adapters and
-in-flight turns are untouched. Deleting a profile stops and unroutes its
-adapters the same way, and `hermes profile rename` unroutes the old name before
-the directory moves and hot-serves the new one (the old name is not resurrected
-by the adapters or the cron ticker that were still bound to it). The
-one-credential-one-poller rule still applies: a
-hot-added profile that reuses another profile's token is parked with a
-`duplicate_credential` error, never started as a second poller.
-
-### Routing shared-bot chats to profiles (`profile_routes`)
-
-Multiplexing selects a profile per **credential** (each profile's own bot
-token) or per **URL prefix** (`/p/<profile>/` for HTTP platforms). When several
-communities share **one** bot token — for example one Discord bot serving many
-guilds — you can additionally route specific guilds/channels/threads to
-different profiles with `gateway.profile_routes`:
-
-```yaml
-gateway:
-  multiplex_profiles: true
-  profile_routes:
-    # An entire Discord server → one profile
-    - name: acme-server
-      platform: discord
-      guild_id: "1234567890"
-      profile: acme
-
-    # One channel in that server → a different profile
-    - name: acme-support
-      platform: discord
-      guild_id: "1234567890"
-      chat_id: "9876543210"
-      profile: acme-support
-
-    # A Telegram group (no guild concept — chat_id only)
-    - name: tg-group
-      platform: telegram
-      chat_id: "-1001234567890"
-      profile: tg-profile
-
-    # A WhatsApp DM — write the phone number; JID and LID forms also match
-    - name: owner-whatsapp
-      platform: whatsapp
-      chat_id: "15551234567"
-      profile: owner
-```
-
-Routes are matched most-specific-first (`thread_id` > `chat_id` > `guild_id`),
-all declared fields must hold (AND), and a route keyed on a channel also
-matches threads/forum posts whose parent is that channel. Messages that match
-no route stay on the default/active profile. The routed profile gets the full
-per-profile isolation described above (config, skills, memory, credentials,
-session namespace). Routing works on every platform adapter, not just Discord.
-
-A route applies only to messages received by the **default profile's bot**
-unless it names another bot with `bot_profile: <profile>`. Telegram DMs use the
-same `chat_id` for every bot (the user's id), so without this a
-`chat_id` route meant for the shared bot would also capture that user's DMs
-with a secondary profile's dedicated bot. Messages arriving at a secondary
-profile's own bot stay in that profile:
-
-```yaml
-    # Pin one user's DM with team_b's OWN bot to a third profile
-    - name: teamb-owner-dm
-      platform: telegram
-      bot_profile: team_b
-      chat_id: "72719239"
-      profile: ops-for-team-b
-```
-
-Authorization for a routed message is always decided by the **receiving bot's
-profile** (its token and allowlist), including follow-ups sent while the agent
-is busy and mid-turn checks such as `/topic` or `/stop`; the routed profile
-itself needs no copy of the allowlist. A routed profile without a bot of its
-own also receives background notifications (process completions, heartbeats,
-async delegation results) through the shared bot after a gateway restart.
-
-On WhatsApp and WhatsApp Cloud, a `chat_id` route matches across user-identity
-forms: a bare phone number (`15551234567`), a JID
-(`15551234567@s.whatsapp.net`), and a LID (`…@lid`) all refer to the same
-person once the bridge has paired them (the same canonicalization session keys
-and adapter allowlists already use). You can put the phone number in
-`profile_routes` and inbound DMs still match whether WhatsApp delivers a JID or
-a LID. Without a LID mapping yet, the number form still matches a JID (the
-suffix is stripped) but cannot resolve an unknown LID — that inbound falls
-through to the default profile until the mapping appears. Group chats
-(`…@g.us`) are not sender identities and still match exactly. Telegram numeric
-ids are unchanged.
-
-`profile_routes` requires `gateway.multiplex_profiles: true`; with
-multiplexing off the routes are ignored. If an explicit route matches but its
-target profile is not installed (or was deleted), the gateway rejects that ingress and logs the route and target. It does not run
-the default profile. Traffic that matches no route keeps the historical
-default-profile behavior.
-
-Cron jobs owned by a routed profile deliver through the shared bot too, but
-only to targets an enabled route with a `chat_id`/`thread_id` maps to that
-profile (a `guild_id + chat_id` route qualifies its channel) — a routed
-profile's job targeting an unrouted chat (or a chat routed to another profile)
-is never sent through the shared bot. Guild-only routes do not qualify a cron
-target; add a `chat_id` route for the delivery channel. The routed profile does
-not need its own `platforms.<platform>` block for this: the shared bot's
-authorization comes from the route, not from the satellite's config.
-
-## Start, stop, or restart all gateways at once
-
-The CLI ships with single-profile lifecycle commands. To act across every
-profile, wrap them in a shell loop. Put the snippet below in
-`~/.local/bin/hermes-gateways` and `chmod +x` it:
-
-```sh
-#!/bin/sh
-set -eu
-
-# Add or remove profile names here as you create / delete profiles.
-profiles="default coder personal-bot research"
-
-usage() {
-  echo "Usage: hermes-gateways {start|stop|restart|status|list}"
-}
-
-run_for_profile() {
-  profile="$1"
-  action="$2"
-  if [ "$profile" = "default" ]; then
-    hermes gateway "$action"
-  else
-    hermes -p "$profile" gateway "$action"
-  fi
-}
-
-action="${1:-}"
-case "$action" in
-  start|stop|restart|status)
-    for profile in $profiles; do
-      echo "==> $action $profile"
-      run_for_profile "$profile" "$action"
-    done
-    ;;
-  list)
-    hermes gateway list
-    ;;
-  *)
-    usage
-    exit 2
-    ;;
-esac
-```
-
-Then:
-
-```bash
-hermes-gateways start      # start every configured profile
-hermes-gateways stop       # stop every configured profile
-hermes-gateways restart    # restart all
-hermes-gateways status     # status across all
-hermes-gateways list       # delegates to `hermes gateway list`
-```
-
-:::tip
-The `default` profile is targeted with `hermes gateway <action>` (no `-p`),
-not `hermes -p default gateway <action>`. The wrapper above handles both forms.
-:::
-
-## Manage one profile
-
-The shortcut commands every profile installs:
-
-```bash
-coder gateway run        # foreground (Ctrl-C to stop)
-coder gateway start      # start the managed service
-coder gateway stop       # stop the managed service
-coder gateway restart    # restart
-coder gateway status     # status
-coder gateway install    # create the LaunchAgent / systemd unit
-coder gateway uninstall  # remove the service file
-```
-
-These are equivalent to `hermes -p coder gateway <action>` — useful if a
-profile alias is not on `PATH` or if you target profiles dynamically from a
-script.
-
-## Service files
-
-Each profile installs its own service with a unique name, so installations
-never clash:
-
-| Platform | Path                                                              |
-| -------- | ----------------------------------------------------------------- |
-| macOS    | `~/Library/LaunchAgents/ai.hermes.gateway-<profile>.plist`        |
-| Linux    | `~/.config/systemd/user/hermes-gateway-<profile>.service`         |
-
-The default profile keeps the historical names: `ai.hermes.gateway.plist` /
-`hermes-gateway.service`.
-
-## Viewing logs
-
-Each profile writes to its own log files:
-
-```bash
-# Default profile
-tail -f ~/.hermes/logs/gateway.log
-tail -f ~/.hermes/logs/gateway.error.log
-
-# Named profile
-tail -f ~/.hermes/profiles/<name>/logs/gateway.log
-tail -f ~/.hermes/profiles/<name>/logs/gateway.error.log
-```
-
-Stream every profile's log simultaneously:
-
-```bash
-tail -f ~/.hermes/logs/gateway.log ~/.hermes/profiles/*/logs/gateway.log
-```
-
-The CLI also has a structured log viewer:
-
-```bash
-hermes logs -f                  # follow default profile
-hermes -p coder logs -f         # follow one profile
-hermes logs --help              # filters, levels, JSON output
-```
-
-## Identify what's actually running
-
-```bash
-hermes profile list             # profiles + model + gateway state
-hermes-gateways status          # full status across every profile
-launchctl list | grep hermes    # macOS — PIDs and labels
-systemctl --user list-units 'hermes-gateway-*'   # Linux — units
-```
-
-## Editing configuration
-
-Every profile keeps its config inside its own directory:
-
-```
-~/.hermes/profiles/<name>/
-├── .env              # API keys, bot tokens (chmod 600)
-├── config.yaml       # model, provider, toolsets, gateway settings
-└── SOUL.md           # personality / system prompt
-```
-
-The default profile uses `~/.hermes/` directly with the same three files.
-
-Edit them with any editor or via the CLI:
-
-```bash
-hermes config set model.model anthropic/claude-sonnet-4    # default profile
-coder config set model.model openai/gpt-5                  # named profile
-```
-
-After editing `.env` or `config.yaml`, restart the affected gateway:
-
-```bash
-coder gateway restart
-# or, for everything:
-hermes-gateways restart
-```
-
-## Keeping the host awake
-
-The gateway process can run all day, but the operating system will still try
-to sleep when idle. Two patterns:
-
-### macOS — `caffeinate`
-
-`caffeinate` is built into macOS and prevents sleep while it runs. No install.
-
-```bash
-caffeinate -dis                    # block display, idle, and system sleep
-caffeinate -dis -t 28800           # same, auto-exit after 8 hours
-caffeinate -i -w $(cat ~/.hermes/gateway.pid) &   # awake while default gateway runs
-
-# Persistent: run in background and forget
-nohup caffeinate -dis >/dev/null 2>&1 &
-disown
-
-# Inspect / stop
-pmset -g assertions | grep -iE 'caffeinate|prevent|user is active'
-pkill caffeinate
-```
-
-| Flag   | Effect                                            |
-| ------ | ------------------------------------------------- |
-| `-d`   | block display sleep                               |
-| `-i`   | block idle system sleep (default)                 |
-| `-m`   | block disk sleep                                  |
-| `-s`   | block system sleep (AC-powered Macs only)         |
-| `-u`   | simulate user activity (prevents screen lock)     |
-| `-t N` | auto-exit after `N` seconds                       |
-| `-w P` | exit when PID `P` exits                           |
-
-:::warning Lid-close still sleeps the Mac
-`caffeinate` cannot override the hardware-driven lid-close sleep on MacBooks.
-For lid-closed operation, change your Energy Saver / Battery preferences or
-use a third-party tool.
-:::
-
-### Linux — `systemd-inhibit` or `loginctl`
-
-```bash
-# Inhibit suspend while a command runs
-systemd-inhibit --what=idle:sleep --who=hermes --why="gateways running" \
-  sleep infinity &
-
-# Allow user services to keep running after logout (recommended)
-sudo loginctl enable-linger "$USER"
-```
-
-After enabling lingering, your systemd user units (including
-`hermes-gateway-<profile>.service`) continue running across SSH disconnects
-and reboots.
-
-## Token-conflict safety
-
-Each profile must use unique bot tokens for each platform. If two profiles
-share a Telegram, Discord, Slack, WhatsApp, or Signal token, the second
-gateway refuses to start with an error naming the conflicting profile. Under
-[multiplexing](#alternative-one-gateway-for-all-profiles-multiplexing) the same
-rule parks only the duplicate profile's adapter and the shared gateway keeps
-running.
-
-To audit:
-
-```bash
-grep -H 'TELEGRAM_BOT_TOKEN\|DISCORD_BOT_TOKEN' \
-     ~/.hermes/.env ~/.hermes/profiles/*/.env
-```
-
-## Migrating from per-profile gateways
-
-If your profiles each run their own gateway today (one systemd unit or launchd
-agent per profile), the default gateway's boot preflight keeps it standalone
-(the unset default never double-binds a running fleet). Fold them into a single
-multiplexed default gateway with one command — and roll back with another.
-Standalone per-profile gateways remain fully supported; this is an optional
-migration, not a removal.
-
-```bash
-hermes gateway migrate --multiplex --dry-run   # print the plan and any blockers; changes nothing
-hermes gateway migrate --multiplex             # apply (asks for confirmation on a TTY; -y skips)
-hermes gateway migrate --standalone            # roll back to per-profile gateways
-```
-
-### What `hermes update` does
-
-After a successful update, when the install has two or more profiles, at least
-one secondary profile runs its own gateway (a live process or an installed
-service) and `gateway.multiplex_profiles` is off, `hermes update` runs the same
-preflight:
-
-- **Nothing blocks it** → the migration runs automatically (the same code path
-  as `hermes gateway migrate --multiplex --yes`) and prints what it did. This
-  is deterministic and never prompts, so it also runs on headless/cron updates.
-- **Something blocks it** → a warning block lists each blocker with its exact
-  fix and the one-liner to run later. Nothing is changed.
-
-Single-profile installs are never migrated (there is nothing to gain), and an
-install that is already multiplexing is left alone. `hermes update` also does
-nothing when no secondary profile runs its own gateway — it never flips modes
-on an install where nothing was running.
-
-### Boundaries `hermes update` never crosses on its own
-
-The unattended hook only folds profiles that share **one UNIX user, one service
-domain and one `profiles/` tree** — the shape `hermes profile create` produces.
-A standalone secondary behind any of these boundaries stops the automatic path:
-
-| boundary | example |
-|---|---|
-| different service manager or scope | default on user systemd, a secondary on **system** systemd (or launchd), or the default detached with a service-managed secondary |
-| more than one installed unit on a profile | a user **and** a system unit for the same profile (the explicit command removes both) |
-| different UNIX user | a system unit with its own `User=`, or a live gateway owned by another uid; a system unit whose `User=` this host cannot resolve — on the secondary **or** on the default — counts as unknown, never as "same user" |
-| `HERMES_HOME` outside `<default home>/profiles/` | a unit pinning `HERMES_HOME=/opt/hermes/profiles/emma` |
-
-In that case `hermes update` prints the boundary it found plus
-`hermes gateway migrate --multiplex`, and changes nothing — no unit is removed
-and `gateway.multiplex_profiles` stays off. Collapsing such a fleet replaces a
-kernel-enforced boundary (file ownership, `User=`) with in-process isolation,
-which is an operator's decision. The explicit command still makes it: the same
-findings appear as **notices** in `hermes gateway migrate --multiplex --dry-run`
-so you can read them first, and `--multiplex` proceeds when you confirm.
-
-### Opting out of the automatic migration
-
-Set `gateway.auto_multiplex_migration: false` on the **default** profile to keep
-the automatic fold from ever running on this install:
-
-```bash
-hermes config set gateway.auto_multiplex_migration false
-```
-
-`hermes update` then leaves per-profile gateways exactly as they are, with no
-output and no changes, however eligible the install looks. The setting lives in
-config, so it survives updates — the decision is made once rather than
-re-litigated on every release. It is read from the effective config like every
-other setting, so a value pinned in the managed scope (`/etc/hermes/config.yaml`)
-wins over the profile's own file. It governs the **automatic** path only:
-`hermes gateway migrate --multiplex` is an explicit request and still migrates
-(and is the supported way to opt back in). Absent or `true` keeps the default
-behaviour described above.
-
-The explicit command is different: `hermes gateway migrate --multiplex` with
-two or more profiles and **no** standalone secondary gateway still applies the
-one remaining step — it sets `gateway.multiplex_profiles: true`, (re)starts the
-default gateway and writes the same rollback manifest (with an empty
-`secondaries` list), so `--standalone` undoes it. You asked for multiplex; you
-get multiplex.
-
-:::tip Clones do not carry channels
-`hermes profile create --clone` leaves the source's bot tokens and allowlists
-behind (see [Profiles → messaging channels are never cloned](./profiles.md#messaging-channels-are-never-cloned---clone-channels-to-opt-in)),
-so a fleet of clones no longer trips the duplicate-credential blocker below.
-Older clones that still carry them are flagged by `hermes profile list`.
-:::
-
-### What the migration does
-
-1. Stops each secondary profile's standalone gateway and uninstalls its
-   service (systemd user/system unit or launchd agent). What was removed is
-   recorded in `~/.hermes/gateway_migration.json` for rollback.
-2. Sets `gateway.multiplex_profiles: true` in the **default** profile's
-   `config.yaml`.
-3. Restarts the default gateway — or installs and starts it on the same service
-   manager the secondaries were using, so a systemd-managed fleet stays
-   systemd-managed.
-4. Waits for the default gateway to record `served_profiles` covering every
-   profile, then prints a summary.
-
-### Blockers and fixes
-
-| Blocker | Why | Fix |
-|---|---|---|
-| Two profiles configure the same platform credential (e.g. the same `TELEGRAM_BOT_TOKEN`) | Under one process a bot token can only be polled once; the multiplexer would park the duplicate and that profile's bot would go silent | Remove the token from the second profile, or keep it in `default` and route that profile's chats with [`profile_routes`](#routing-shared-bot-chats-to-profiles-profile_routes) |
-| A secondary profile enables a port-binding platform that has **no** `/p/<profile>/` ingress on the default listener | The multiplexer skips that whole profile (see [rule 2](#2-http-inbound-platforms-are-reached-via-a-pprofile-url-prefix)) | Disable the platform in that profile (`platforms.<name>.enabled: false`), or keep the profile on a standalone gateway with `hermes -p <name> gateway start --force` |
-
-The credential check reuses the gateway's own conflict detection, so its verdict
-matches what the multiplexer does at startup. Which port-binding platforms have
-a `/p/<profile>/` ingress is read from the adapters themselves (each declares
-`serves_profile_prefix`), so the preflight stays correct as new HTTP-inbound
-adapters gain the prefix.
-
-### What changes for inbound-port profiles
-
-A secondary profile that used `api_server` or `webhook` on its own port is
-**not** blocked — but its URL changes. The preflight prints the exact new URL,
-for example:
-
-```
-Profile 'coder': api_server moves onto the default listener at
-http://127.0.0.1:8642/p/coder/v1/... (its key/secret is unchanged; update
-clients that call the old per-profile port).
-```
-
-The profile's own `API_SERVER_KEY` / webhook secret keeps authenticating the
-prefixed URL; nothing else about the key changes.
-
-### Profiles created after the migration
-
-A profile created while the multiplexer runs is served without a restart (see
-above). `hermes profile create` confirms this when the live multiplexer picked the
-profile up; it prints the `hermes gateway restart` reminder only when it could not
-reach the multiplexer (for example, a gateway started from an older build).
-
-### Rollback
-
-```bash
-hermes gateway migrate --standalone
-```
-
-reads `gateway_migration.json`, sets `gateway.multiplex_profiles` back to its
-previous value, restarts the default gateway, and reinstalls/starts every
-recorded per-profile service (a system unit comes back with the `User=` it had).
-The manifest is removed once everything is back.
-
-The forward migration is transactional in the same way. Failures it can see
-coming from the plan (a system unit that would have to run as root without a
-recorded `User=`, a config file it cannot rewrite) are refused before any
-per-profile gateway is stopped. Anything that fails after the manifest is
-written — the flag write, a later secondary's stop or unit removal, the
-default's install or start — rolls back through the manifest on the spot, so no
-profile is left without a gateway. Should the process die anywhere in that
-window, the next `hermes gateway migrate --multiplex` sees the flag on, the
-manifest, and no live multiplexer serving the migrated profiles (an installed
-but stopped default unit does not count) and resumes from the manifest instead
-of reporting "already multiplexed".
-If no manifest exists (you enabled multiplexing by hand), leave multiplex mode
-with `hermes config set gateway.multiplex_profiles false && hermes gateway restart`
-and reinstall the per-profile services you want.
-
-Not covered automatically: s6-supervised containers (set the flag on the
-default profile and restart the container) and Windows Scheduled Tasks (set the
-flag, stop the per-profile tasks, `hermes gateway restart`). The dashboard's
-System page offers the same migration as a button when the preflight finds an
-eligible install.
-
-## Updating the code
-
-`hermes update` pulls the latest code once and syncs new bundled skills into
-every profile:
-
-```bash
-hermes update
-hermes-gateways restart
-```
-
-Running gateways are restarted by the update itself; on an install that still
-runs one gateway per profile, the update then offers the
-[migration to a single multiplexed gateway](#migrating-from-per-profile-gateways)
-— automatically when nothing blocks it, otherwise as a warning with the fixes.
-
-User-modified skills are never overwritten.
-
-## Troubleshooting
-
-### "Could not find service in domain for user gui: 501"
-
-You ran `hermes gateway start` after a previous `hermes gateway stop`. The
-CLI's `stop` does a full `launchctl unload`, which removes the service from
-launchd's registry. The CLI catches this specific error on `start` and
-automatically re-loads the plist (`↻ launchd job was unloaded; reloading
-service definition`). The service starts normally. Nothing to fix.
-
-### Stale PID after a crash
-
-If a profile's gateway shows `not running` but a process is still alive:
-
-```bash
-ps -ef | grep "hermes_cli.*-p <profile>"
-cat ~/.hermes/profiles/<profile>/gateway.pid
-kill -TERM <pid>          # graceful
-kill -KILL <pid>          # if that fails after a few seconds
-<profile> gateway start
-```
-
-### Forcing a hard reset of one service
-
-```bash
-# macOS
-launchctl unload ~/Library/LaunchAgents/ai.hermes.gateway-<profile>.plist
-launchctl load   ~/Library/LaunchAgents/ai.hermes.gateway-<profile>.plist
-
-# Linux
-systemctl --user restart hermes-gateway-<profile>.service
-```
-
-### Health check
-
-```bash
-hermes doctor                  # default profile
-hermes -p <profile> doctor     # one profile
-```