durar-ai 2026.4.4

package/docs/gateway/multiple-gateways.md

@@ -0,0 +1,120 @@
+---
+summary: "Run multiple Durar 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"
+---
+
+# Multiple Gateways (same host)
+
+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.
+
+## Isolation checklist (required)
+
+- `Durar_CONFIG_PATH` — per-instance config file
+- `Durar_STATE_DIR` — per-instance sessions, creds, caches
+- `agents.defaults.workspace` — per-instance workspace root
+- `gateway.port` (or `--port`) — unique per instance
+- Derived ports (browser/canvas) must not overlap
+
+If these are shared, you will hit config races and port conflicts.
+
+## Recommended: profiles (`--profile`)
+
+Profiles auto-scope `Durar_STATE_DIR` + `Durar_CONFIG_PATH` and suffix service names.
+
+```bash
+# main
+Durar --profile main setup
+Durar --profile main gateway --port 18789
+
+# rescue
+Durar --profile rescue setup
+Durar --profile rescue gateway --port 19001
+```
+
+Per-profile services:
+
+```bash
+Durar --profile main gateway install
+Durar --profile rescue gateway install
+```
+
+## Rescue-bot guide
+
+Run a second Gateway on the same host with its own:
+
+- profile/config
+- state dir
+- workspace
+- base port (plus derived ports)
+
+This keeps the rescue bot isolated from the main bot so it can debug or apply config changes if the primary bot is down.
+
+Port spacing: leave at least 20 ports between base ports so the derived browser/canvas/CDP ports never collide.
+
+### How to install (rescue bot)
+
+```bash
+# Main bot (existing or fresh, without --profile param)
+# Runs on port 18789 + Chrome CDC/Canvas/... Ports
+Durar onboard
+Durar gateway install
+
+# Rescue bot (isolated profile + ports)
+Durar --profile rescue onboard
+# Notes:
+# - workspace name will be postfixed with -rescue per default
+# - Port should be at least 18789 + 20 Ports,
+#   better choose completely different base port, like 19789,
+# - rest of the onboarding is the same as normal
+
+# To install the service (if not happened automatically during setup)
+Durar --profile rescue gateway install
+```
+
+## Port mapping (derived)
+
+Base port = `gateway.port` (or `Durar_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
+Durar_CONFIG_PATH=~/.Durar/main.json \
+Durar_STATE_DIR=~/.Durar-main \
+Durar gateway --port 18789
+
+Durar_CONFIG_PATH=~/.Durar/rescue.json \
+Durar_STATE_DIR=~/.Durar-rescue \
+Durar gateway --port 19001
+```
+
+## Quick checks
+
+```bash
+Durar --profile main gateway status --deep
+Durar --profile rescue gateway status --deep
+Durar --profile rescue gateway probe
+Durar --profile main status
+Durar --profile rescue status
+Durar --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.

package/docs/gateway/network-model.md

@@ -0,0 +1,25 @@
+---
+summary: "How the Gateway, nodes, and canvas host connect."
+read_when:
+  - You want a concise view of the Gateway networking model
+title: "Network model"
+---
+
+# Network Model
+
+> This content has been merged into [Network](/network#core-model). See that page for the current guide.
+
+Most operations flow through the Gateway (`Durar gateway`), a single long-running
+process that owns channel connections and the WebSocket control plane.
+
+## Core rules
+
+- One Gateway per host is recommended. It is the only process allowed to own the WhatsApp Web session. For rescue bots or strict isolation, run multiple gateways with isolated profiles and ports. See [Multiple gateways](/gateway/multiple-gateways).
+- Loopback first: the Gateway WS defaults to `ws://127.0.0.1:18789`. The wizard creates shared-secret auth by default and usually generates a token, even for loopback. For non-loopback access, use a valid gateway auth path: shared-secret token/password auth, or a correctly configured non-loopback `trusted-proxy` deployment. Tailnet/mobile setups usually work best through Tailscale Serve or another `wss://` endpoint instead of raw tailnet `ws://`.
+- Nodes connect to the Gateway WS over LAN, tailnet, or SSH as needed. The
+  legacy TCP bridge has been removed.
+- Canvas host is served by the Gateway HTTP server on the **same port** as the Gateway (default `18789`):
+  - `/__Durar__/canvas/`
+  - `/__Durar__/a2ui/`
+    When `gateway.auth` is configured and the Gateway binds beyond loopback, these routes are protected by Gateway auth. Node clients use node-scoped capability URLs tied to their active WS session. See [Gateway configuration](/gateway/configuration) (`canvasHost`, `gateway`).
+- Remote use is typically SSH tunnel or tailnet VPN. See [Remote access](/gateway/remote) and [Discovery](/gateway/discovery).

package/docs/gateway/openai-http-api.md

@@ -0,0 +1,280 @@
+---
+summary: "Expose an OpenAI-compatible /v1/chat/completions HTTP endpoint from the Gateway"
+read_when:
+  - Integrating tools that expect OpenAI Chat Completions
+title: "OpenAI Chat Completions"
+---
+
+# OpenAI Chat Completions (HTTP)
+
+Durar’s Gateway can serve a small OpenAI-compatible Chat Completions endpoint.
+
+This endpoint is **disabled by default**. Enable it in config first.
+
+- `POST /v1/chat/completions`
+- Same port as the Gateway (WS + HTTP multiplex): `http://<gateway-host>:<port>/v1/chat/completions`
+
+When the Gateway’s OpenAI-compatible HTTP surface is enabled, it also serves:
+
+- `GET /v1/models`
+- `GET /v1/models/{id}`
+- `POST /v1/embeddings`
+- `POST /v1/responses`
+
+Under the hood, requests are executed as a normal Gateway agent run (same codepath as `Durar agent`), so routing/permissions/config match your Gateway.
+
+## Authentication
+
+Uses the Gateway auth configuration.
+
+Common HTTP auth paths:
+
+- shared-secret auth (`gateway.auth.mode="token"` or `"password"`):
+  `Authorization: Bearer <token-or-password>`
+- trusted identity-bearing HTTP auth (`gateway.auth.mode="trusted-proxy"`):
+  route through the configured identity-aware proxy and let it inject the
+  required identity headers
+- private-ingress open auth (`gateway.auth.mode="none"`):
+  no auth header required
+
+Notes:
+
+- When `gateway.auth.mode="token"`, use `gateway.auth.token` (or `Durar_GATEWAY_TOKEN`).
+- When `gateway.auth.mode="password"`, use `gateway.auth.password` (or `Durar_GATEWAY_PASSWORD`).
+- When `gateway.auth.mode="trusted-proxy"`, the HTTP request must come from a
+  configured non-loopback trusted proxy source; same-host loopback proxies do
+  not satisfy this mode.
+- If `gateway.auth.rateLimit` is configured and too many auth failures occur, the endpoint returns `429` with `Retry-After`.
+
+## Security boundary (important)
+
+Treat this endpoint as a **full operator-access** surface for the gateway instance.
+
+- HTTP bearer auth here is not a narrow per-user scope model.
+- A valid Gateway token/password for this endpoint should be treated like an owner/operator credential.
+- Requests run through the same control-plane agent path as trusted operator actions.
+- There is no separate non-owner/per-user tool boundary on this endpoint; once a caller passes Gateway auth here, Durar treats that caller as a trusted operator for this gateway.
+- For shared-secret auth modes (`token` and `password`), the endpoint restores the normal full operator defaults even if the caller sends a narrower `x-Durar-scopes` header.
+- Trusted identity-bearing HTTP modes (for example trusted proxy auth or `gateway.auth.mode="none"`) honor `x-Durar-scopes` when present and otherwise fall back to the normal operator default scope set.
+- If the target agent policy allows sensitive tools, this endpoint can use them.
+- Keep this endpoint on loopback/tailnet/private ingress only; do not expose it directly to the public internet.
+
+Auth matrix:
+
+- `gateway.auth.mode="token"` or `"password"` + `Authorization: Bearer ...`
+  - proves possession of the shared gateway operator secret
+  - ignores narrower `x-Durar-scopes`
+  - restores the full default operator scope set:
+    `operator.admin`, `operator.approvals`, `operator.pairing`,
+    `operator.read`, `operator.talk.secrets`, `operator.write`
+  - treats chat turns on this endpoint as owner-sender turns
+- trusted identity-bearing HTTP modes (for example trusted proxy auth, or `gateway.auth.mode="none"` on private ingress)
+  - authenticate some outer trusted identity or deployment boundary
+  - honor `x-Durar-scopes` when the header is present
+  - fall back to the normal operator default scope set when the header is absent
+  - only lose owner semantics when the caller explicitly narrows scopes and omits `operator.admin`
+
+See [Security](/gateway/security) and [Remote access](/gateway/remote).
+
+## Agent-first model contract
+
+Durar treats the OpenAI `model` field as an **agent target**, not a raw provider model id.
+
+- `model: "Durar"` routes to the configured default agent.
+- `model: "Durar/default"` also routes to the configured default agent.
+- `model: "Durar/<agentId>"` routes to a specific agent.
+
+Optional request headers:
+
+- `x-Durar-model: <provider/model-or-bare-id>` overrides the backend model for the selected agent.
+- `x-Durar-agent-id: <agentId>` remains supported as a compatibility override.
+- `x-Durar-session-key: <sessionKey>` fully controls session routing.
+- `x-Durar-message-channel: <channel>` sets the synthetic ingress channel context for channel-aware prompts and policies.
+
+Compatibility aliases still accepted:
+
+- `model: "Durar:<agentId>"`
+- `model: "agent:<agentId>"`
+
+## Enabling the endpoint
+
+Set `gateway.http.endpoints.chatCompletions.enabled` to `true`:
+
+```json5
+{
+  gateway: {
+    http: {
+      endpoints: {
+        chatCompletions: { enabled: true },
+      },
+    },
+  },
+}
+```
+
+## Disabling the endpoint
+
+Set `gateway.http.endpoints.chatCompletions.enabled` to `false`:
+
+```json5
+{
+  gateway: {
+    http: {
+      endpoints: {
+        chatCompletions: { enabled: false },
+      },
+    },
+  },
+}
+```
+
+## Session behavior
+
+By default the endpoint is **stateless per request** (a new session key is generated each call).
+
+If the request includes an OpenAI `user` string, the Gateway derives a stable session key from it, so repeated calls can share an agent session.
+
+## Why this surface matters
+
+This is the highest-leverage compatibility set for self-hosted frontends and tooling:
+
+- Most Open WebUI, LobeChat, and LibreChat setups expect `/v1/models`.
+- Many RAG systems expect `/v1/embeddings`.
+- Existing OpenAI chat clients can usually start with `/v1/chat/completions`.
+- More agent-native clients increasingly prefer `/v1/responses`.
+
+## Model list and agent routing
+
+<AccordionGroup>
+  <Accordion title="What does `/v1/models` return?">
+    An Durar agent-target list.
+
+    The returned ids are `Durar`, `Durar/default`, and `Durar/<agentId>` entries.
+    Use them directly as OpenAI `model` values.
+
+  </Accordion>
+  <Accordion title="Does `/v1/models` list agents or sub-agents?">
+    It lists top-level agent targets, not backend provider models and not sub-agents.
+
+    Sub-agents remain internal execution topology. They do not appear as pseudo-models.
+
+  </Accordion>
+  <Accordion title="Why is `Durar/default` included?">
+    `Durar/default` is the stable alias for the configured default agent.
+
+    That means clients can keep using one predictable id even if the real default agent id changes between environments.
+
+  </Accordion>
+  <Accordion title="How do I override the backend model?">
+    Use `x-Durar-model`.
+
+    Examples:
+    `x-Durar-model: openai/gpt-5.4`
+    `x-Durar-model: gpt-5.4`
+
+    If you omit it, the selected agent runs with its normal configured model choice.
+
+  </Accordion>
+  <Accordion title="How do embeddings fit this contract?">
+    `/v1/embeddings` uses the same agent-target `model` ids.
+
+    Use `model: "Durar/default"` or `model: "Durar/<agentId>"`.
+    When you need a specific embedding model, send it in `x-Durar-model`.
+    Without that header, the request passes through to the selected agent's normal embedding setup.
+
+  </Accordion>
+</AccordionGroup>
+
+## Streaming (SSE)
+
+Set `stream: true` to receive Server-Sent Events (SSE):
+
+- `Content-Type: text/event-stream`
+- Each event line is `data: <json>`
+- Stream ends with `data: [DONE]`
+
+## Open WebUI quick setup
+
+For a basic Open WebUI connection:
+
+- Base URL: `http://127.0.0.1:18789/v1`
+- Docker on macOS base URL: `http://host.docker.internal:18789/v1`
+- API key: your Gateway bearer token
+- Model: `Durar/default`
+
+Expected behavior:
+
+- `GET /v1/models` should list `Durar/default`
+- Open WebUI should use `Durar/default` as the chat model id
+- If you want a specific backend provider/model for that agent, set the agent's normal default model or send `x-Durar-model`
+
+Quick smoke:
+
+```bash
+curl -sS http://127.0.0.1:18789/v1/models \
+  -H 'Authorization: Bearer YOUR_TOKEN'
+```
+
+If that returns `Durar/default`, most Open WebUI setups can connect with the same base URL and token.
+
+## Examples
+
+Non-streaming:
+
+```bash
+curl -sS http://127.0.0.1:18789/v1/chat/completions \
+  -H 'Authorization: Bearer YOUR_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "Durar/default",
+    "messages": [{"role":"user","content":"hi"}]
+  }'
+```
+
+Streaming:
+
+```bash
+curl -N http://127.0.0.1:18789/v1/chat/completions \
+  -H 'Authorization: Bearer YOUR_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -H 'x-Durar-model: openai/gpt-5.4' \
+  -d '{
+    "model": "Durar/research",
+    "stream": true,
+    "messages": [{"role":"user","content":"hi"}]
+  }'
+```
+
+List models:
+
+```bash
+curl -sS http://127.0.0.1:18789/v1/models \
+  -H 'Authorization: Bearer YOUR_TOKEN'
+```
+
+Fetch one model:
+
+```bash
+curl -sS http://127.0.0.1:18789/v1/models/Durar%2Fdefault \
+  -H 'Authorization: Bearer YOUR_TOKEN'
+```
+
+Create embeddings:
+
+```bash
+curl -sS http://127.0.0.1:18789/v1/embeddings \
+  -H 'Authorization: Bearer YOUR_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -H 'x-Durar-model: openai/text-embedding-3-small' \
+  -d '{
+    "model": "Durar/default",
+    "input": ["alpha", "beta"]
+  }'
+```
+
+Notes:
+
+- `/v1/models` returns Durar agent targets, not raw provider catalogs.
+- `Durar/default` is always present so one stable id works across environments.
+- Backend provider/model overrides belong in `x-Durar-model`, not the OpenAI `model` field.
+- `/v1/embeddings` supports `input` as a string or array of strings.