durar-ai 2026.4.4

package/docs/gateway/remote-gateway-readme.md

@@ -0,0 +1,164 @@
+---
+summary: "SSH tunnel setup for Durar.app connecting to a remote gateway"
+read_when: "Connecting the macOS app to a remote gateway over SSH"
+title: "Remote Gateway Setup"
+---
+
+> This content has been merged into [Remote Access](/gateway/remote#macos-persistent-ssh-tunnel-via-launchagent). See that page for the current guide.
+
+# Running Durar.app with a Remote Gateway
+
+Durar.app uses SSH tunneling to connect to a remote gateway. This guide shows you how to set it up.
+
+## Overview
+
+```mermaid
+flowchart TB
+    subgraph Client["Client Machine"]
+        direction TB
+        A["Durar.app"]
+        B["ws://127.0.0.1:18789\n(local port)"]
+        T["SSH Tunnel"]
+
+        A --> B
+        B --> T
+    end
+    subgraph Remote["Remote Machine"]
+        direction TB
+        C["Gateway WebSocket"]
+        D["ws://127.0.0.1:18789"]
+
+        C --> D
+    end
+    T --> C
+```
+
+## Quick Setup
+
+### Step 1: Add SSH Config
+
+Edit `~/.ssh/config` and add:
+
+```ssh
+Host remote-gateway
+    HostName <REMOTE_IP>          # e.g., 172.27.187.184
+    User <REMOTE_USER>            # e.g., jefferson
+    LocalForward 18789 127.0.0.1:18789
+    IdentityFile ~/.ssh/id_rsa
+```
+
+Replace `<REMOTE_IP>` and `<REMOTE_USER>` with your values.
+
+### Step 2: Copy SSH Key
+
+Copy your public key to the remote machine (enter password once):
+
+```bash
+ssh-copy-id -i ~/.ssh/id_rsa <REMOTE_USER>@<REMOTE_IP>
+```
+
+### Step 3: Configure Remote Gateway Auth
+
+```bash
+Durar config set gateway.remote.token "<your-token>"
+```
+
+Use `gateway.remote.password` instead if your remote gateway uses password auth.
+`Durar_GATEWAY_TOKEN` is still valid as a shell-level override, but the durable
+remote-client setup is `gateway.remote.token` / `gateway.remote.password`.
+
+### Step 4: Start SSH Tunnel
+
+```bash
+ssh -N remote-gateway &
+```
+
+### Step 5: Restart Durar.app
+
+```bash
+# Quit Durar.app (⌘Q), then reopen:
+open /path/to/Durar.app
+```
+
+The app will now connect to the remote gateway through the SSH tunnel.
+
+---
+
+## Auto-Start Tunnel on Login
+
+To have the SSH tunnel start automatically when you log in, create a Launch Agent.
+
+### Create the PLIST file
+
+Save this as `~/Library/LaunchAgents/ai.Durar.ssh-tunnel.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>ai.Durar.ssh-tunnel</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/usr/bin/ssh</string>
+        <string>-N</string>
+        <string>remote-gateway</string>
+    </array>
+    <key>KeepAlive</key>
+    <true/>
+    <key>RunAtLoad</key>
+    <true/>
+</dict>
+</plist>
+```
+
+### Load the Launch Agent
+
+```bash
+launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.Durar.ssh-tunnel.plist
+```
+
+The tunnel will now:
+
+- Start automatically when you log in
+- Restart if it crashes
+- Keep running in the background
+
+Legacy note: remove any leftover `com.Durar.ssh-tunnel` LaunchAgent if present.
+
+---
+
+## Troubleshooting
+
+**Check if tunnel is running:**
+
+```bash
+ps aux | grep "ssh -N remote-gateway" | grep -v grep
+lsof -i :18789
+```
+
+**Restart the tunnel:**
+
+```bash
+launchctl kickstart -k gui/$UID/ai.Durar.ssh-tunnel
+```
+
+**Stop the tunnel:**
+
+```bash
+launchctl bootout gui/$UID/ai.Durar.ssh-tunnel
+```
+
+---
+
+## How It Works
+
+| Component                            | What It Does                                                 |
+| ------------------------------------ | ------------------------------------------------------------ |
+| `LocalForward 18789 127.0.0.1:18789` | Forwards local port 18789 to remote port 18789               |
+| `ssh -N`                             | SSH without executing remote commands (just port forwarding) |
+| `KeepAlive`                          | Automatically restarts tunnel if it crashes                  |
+| `RunAtLoad`                          | Starts tunnel when the agent loads                           |
+
+Durar.app connects to `ws://127.0.0.1:18789` on your client machine. The SSH tunnel forwards that connection to port 18789 on the remote machine where the Gateway is running.

package/docs/gateway/remote.md

@@ -0,0 +1,251 @@
+---
+summary: "Remote access using SSH tunnels (Gateway WS) and tailnets"
+read_when:
+  - Running or troubleshooting remote gateway setups
+title: "Remote Access"
+---
+
+# Remote access (SSH, tunnels, and tailnets)
+
+This repo supports “remote over SSH” by keeping a single Gateway (the master) running on a dedicated host (desktop/server) and connecting clients to it.
+
+- For **operators (you / the macOS app)**: SSH tunneling is the universal fallback.
+- For **nodes (iOS/Android and future devices)**: connect to the Gateway **WebSocket** (LAN/tailnet or SSH tunnel as needed).
+
+## The core idea
+
+- The Gateway WebSocket binds to **loopback** on your configured port (defaults to 18789).
+- For remote use, you forward that loopback port over SSH (or use a tailnet/VPN and tunnel less).
+
+## Common VPN/tailnet setups (where the agent lives)
+
+Think of the **Gateway host** as “where the agent lives.” It owns sessions, auth profiles, channels, and state.
+Your laptop/desktop (and nodes) connect to that host.
+
+### 1) Always-on Gateway in your tailnet (VPS or home server)
+
+Run the Gateway on a persistent host and reach it via **Tailscale** or SSH.
+
+- **Best UX:** keep `gateway.bind: "loopback"` and use **Tailscale Serve** for the Control UI.
+- **Fallback:** keep loopback + SSH tunnel from any machine that needs access.
+- **Examples:** [exe.dev](/install/exe-dev) (easy VM) or [Hetzner](/install/hetzner) (production VPS).
+
+This is ideal when your laptop sleeps often but you want the agent always-on.
+
+### 2) Home desktop runs the Gateway, laptop is remote control
+
+The laptop does **not** run the agent. It connects remotely:
+
+- Use the macOS app’s **Remote over SSH** mode (Settings → General → “Durar runs”).
+- The app opens and manages the tunnel, so WebChat + health checks “just work.”
+
+Runbook: [macOS remote access](/platforms/mac/remote).
+
+### 3) Laptop runs the Gateway, remote access from other machines
+
+Keep the Gateway local but expose it safely:
+
+- SSH tunnel to the laptop from other machines, or
+- Tailscale Serve the Control UI and keep the Gateway loopback-only.
+
+Guide: [Tailscale](/gateway/tailscale) and [Web overview](/web).
+
+## Command flow (what runs where)
+
+One gateway service owns state + channels. Nodes are peripherals.
+
+Flow example (Telegram → node):
+
+- Telegram message arrives at the **Gateway**.
+- Gateway runs the **agent** and decides whether to call a node tool.
+- Gateway calls the **node** over the Gateway WebSocket (`node.*` RPC).
+- Node returns the result; Gateway replies back out to Telegram.
+
+Notes:
+
+- **Nodes do not run the gateway service.** Only one gateway should run per host unless you intentionally run isolated profiles (see [Multiple gateways](/gateway/multiple-gateways)).
+- macOS app “node mode” is just a node client over the Gateway WebSocket.
+
+## SSH tunnel (CLI + tools)
+
+Create a local tunnel to the remote Gateway WS:
+
+```bash
+ssh -N -L 18789:127.0.0.1:18789 user@host
+```
+
+With the tunnel up:
+
+- `Durar health` and `Durar status --deep` now reach the remote gateway via `ws://127.0.0.1:18789`.
+- `Durar gateway status`, `Durar gateway health`, `Durar gateway probe`, and `Durar gateway call` can also target the forwarded URL via `--url` when needed.
+
+Note: replace `18789` with your configured `gateway.port` (or `--port`/`Durar_GATEWAY_PORT`).
+Note: when you pass `--url`, the CLI does not fall back to config or environment credentials.
+Include `--token` or `--password` explicitly. Missing explicit credentials is an error.
+
+## CLI remote defaults
+
+You can persist a remote target so CLI commands use it by default:
+
+```json5
+{
+  gateway: {
+    mode: "remote",
+    remote: {
+      url: "ws://127.0.0.1:18789",
+      token: "your-token",
+    },
+  },
+}
+```
+
+When the gateway is loopback-only, keep the URL at `ws://127.0.0.1:18789` and open the SSH tunnel first.
+
+## Credential precedence
+
+Gateway credential resolution follows one shared contract across call/probe/status paths and Discord exec-approval monitoring. Node-host uses the same base contract with one local-mode exception (it intentionally ignores `gateway.remote.*`):
+
+- Explicit credentials (`--token`, `--password`, or tool `gatewayToken`) always win on call paths that accept explicit auth.
+- URL override safety:
+  - CLI URL overrides (`--url`) never reuse implicit config/env credentials.
+  - Env URL overrides (`Durar_GATEWAY_URL`) may use env credentials only (`Durar_GATEWAY_TOKEN` / `Durar_GATEWAY_PASSWORD`).
+- Local mode defaults:
+  - token: `Durar_GATEWAY_TOKEN` -> `gateway.auth.token` -> `gateway.remote.token` (remote fallback applies only when local auth token input is unset)
+  - password: `Durar_GATEWAY_PASSWORD` -> `gateway.auth.password` -> `gateway.remote.password` (remote fallback applies only when local auth password input is unset)
+- Remote mode defaults:
+  - token: `gateway.remote.token` -> `Durar_GATEWAY_TOKEN` -> `gateway.auth.token`
+  - password: `Durar_GATEWAY_PASSWORD` -> `gateway.remote.password` -> `gateway.auth.password`
+- Node-host local-mode exception: `gateway.remote.token` / `gateway.remote.password` are ignored.
+- Remote probe/status token checks are strict by default: they use `gateway.remote.token` only (no local token fallback) when targeting remote mode.
+- Gateway env overrides use `Durar_GATEWAY_*` only.
+
+## Chat UI over SSH
+
+WebChat no longer uses a separate HTTP port. The SwiftUI chat UI connects directly to the Gateway WebSocket.
+
+- Forward `18789` over SSH (see above), then connect clients to `ws://127.0.0.1:18789`.
+- On macOS, prefer the app’s “Remote over SSH” mode, which manages the tunnel automatically.
+
+## macOS app "Remote over SSH"
+
+The macOS menu bar app can drive the same setup end-to-end (remote status checks, WebChat, and Voice Wake forwarding).
+
+Runbook: [macOS remote access](/platforms/mac/remote).
+
+## Security rules (remote/VPN)
+
+Short version: **keep the Gateway loopback-only** unless you’re sure you need a bind.
+
+- **Loopback + SSH/Tailscale Serve** is the safest default (no public exposure).
+- Plaintext `ws://` is loopback-only by default. For trusted private networks,
+  set `Durar_ALLOW_INSECURE_PRIVATE_WS=1` on the client process as break-glass.
+- **Non-loopback binds** (`lan`/`tailnet`/`custom`, or `auto` when loopback is unavailable) must use gateway auth: token, password, or an identity-aware reverse proxy with `gateway.auth.mode: "trusted-proxy"`.
+- `gateway.remote.token` / `.password` are client credential sources. They do **not** configure server auth by themselves.
+- Local call paths can use `gateway.remote.*` as fallback only when `gateway.auth.*` is unset.
+- If `gateway.auth.token` / `gateway.auth.password` is explicitly configured via SecretRef and unresolved, resolution fails closed (no remote fallback masking).
+- `gateway.remote.tlsFingerprint` pins the remote TLS cert when using `wss://`.
+- **Tailscale Serve** can authenticate Control UI/WebSocket traffic via identity
+  headers when `gateway.auth.allowTailscale: true`; HTTP API endpoints do not
+  use that Tailscale header auth and instead follow the gateway's normal HTTP
+  auth mode. This tokenless flow assumes the gateway host is trusted. Set it to
+  `false` if you want shared-secret auth everywhere.
+- **Trusted-proxy** auth is for non-loopback identity-aware proxy setups only.
+  Same-host loopback reverse proxies do not satisfy `gateway.auth.mode: "trusted-proxy"`.
+- Treat browser control like operator access: tailnet-only + deliberate node pairing.
+
+Deep dive: [Security](/gateway/security).
+
+### macOS: persistent SSH tunnel via LaunchAgent
+
+For macOS clients connecting to a remote gateway, the easiest persistent setup uses an SSH `LocalForward` config entry plus a LaunchAgent to keep the tunnel alive across reboots and crashes.
+
+#### Step 1: add SSH config
+
+Edit `~/.ssh/config`:
+
+```ssh
+Host remote-gateway
+    HostName <REMOTE_IP>
+    User <REMOTE_USER>
+    LocalForward 18789 127.0.0.1:18789
+    IdentityFile ~/.ssh/id_rsa
+```
+
+Replace `<REMOTE_IP>` and `<REMOTE_USER>` with your values.
+
+#### Step 2: copy SSH key (one-time)
+
+```bash
+ssh-copy-id -i ~/.ssh/id_rsa <REMOTE_USER>@<REMOTE_IP>
+```
+
+#### Step 3: configure the gateway token
+
+Store the token in config so it persists across restarts:
+
+```bash
+Durar config set gateway.remote.token "<your-token>"
+```
+
+#### Step 4: create the LaunchAgent
+
+Save this as `~/Library/LaunchAgents/ai.Durar.ssh-tunnel.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>ai.Durar.ssh-tunnel</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/usr/bin/ssh</string>
+        <string>-N</string>
+        <string>remote-gateway</string>
+    </array>
+    <key>KeepAlive</key>
+    <true/>
+    <key>RunAtLoad</key>
+    <true/>
+</dict>
+</plist>
+```
+
+#### Step 5: load the LaunchAgent
+
+```bash
+launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.Durar.ssh-tunnel.plist
+```
+
+The tunnel will start automatically at login, restart on crash, and keep the forwarded port live.
+
+Note: if you have a leftover `com.Durar.ssh-tunnel` LaunchAgent from an older setup, unload and delete it.
+
+#### Troubleshooting
+
+Check if the tunnel is running:
+
+```bash
+ps aux | grep "ssh -N remote-gateway" | grep -v grep
+lsof -i :18789
+```
+
+Restart the tunnel:
+
+```bash
+launchctl kickstart -k gui/$UID/ai.Durar.ssh-tunnel
+```
+
+Stop the tunnel:
+
+```bash
+launchctl bootout gui/$UID/ai.Durar.ssh-tunnel
+```
+
+| Config entry                         | What it does                                                 |
+| ------------------------------------ | ------------------------------------------------------------ |
+| `LocalForward 18789 127.0.0.1:18789` | Forwards local port 18789 to remote port 18789               |
+| `ssh -N`                             | SSH without executing remote commands (port-forwarding only) |
+| `KeepAlive`                          | Automatically restarts the tunnel if it crashes              |
+| `RunAtLoad`                          | Starts the tunnel when the LaunchAgent loads at login        |

package/docs/gateway/sandbox-vs-tool-policy-vs-elevated.md

@@ -0,0 +1,141 @@
+---
+title: Sandbox vs Tool Policy vs Elevated
+summary: "Why a tool is blocked: sandbox runtime, tool allow/deny policy, and elevated exec gates"
+read_when: "You hit 'sandbox jail' or see a tool/elevated refusal and want the exact config key to change."
+status: active
+---
+
+# Sandbox vs Tool Policy vs Elevated
+
+Durar has three related (but different) controls:
+
+1. **Sandbox** (`agents.defaults.sandbox.*` / `agents.list[].sandbox.*`) decides **where tools run** (Docker vs host).
+2. **Tool policy** (`tools.*`, `tools.sandbox.tools.*`, `agents.list[].tools.*`) decides **which tools are available/allowed**.
+3. **Elevated** (`tools.elevated.*`, `agents.list[].tools.elevated.*`) is an **exec-only escape hatch** to run outside the sandbox when you’re sandboxed (`gateway` by default, or `node` when the exec target is configured to `node`).
+
+## Quick debug
+
+Use the inspector to see what Durar is _actually_ doing:
+
+```bash
+Durar sandbox explain
+Durar sandbox explain --session agent:main:main
+Durar sandbox explain --agent work
+Durar sandbox explain --json
+```
+
+It prints:
+
+- effective sandbox mode/scope/workspace access
+- whether the session is currently sandboxed (main vs non-main)
+- effective sandbox tool allow/deny (and whether it came from agent/global/default)
+- elevated gates and fix-it key paths
+
+## Sandbox: where tools run
+
+Sandboxing is controlled by `agents.defaults.sandbox.mode`:
+
+- `"off"`: everything runs on the host.
+- `"non-main"`: only non-main sessions are sandboxed (common “surprise” for groups/channels).
+- `"all"`: everything is sandboxed.
+
+See [Sandboxing](/gateway/sandboxing) for the full matrix (scope, workspace mounts, images).
+
+### Bind mounts (security quick check)
+
+- `docker.binds` _pierces_ the sandbox filesystem: whatever you mount is visible inside the container with the mode you set (`:ro` or `:rw`).
+- Default is read-write if you omit the mode; prefer `:ro` for source/secrets.
+- `scope: "shared"` ignores per-agent binds (only global binds apply).
+- Durar validates bind sources twice: first on the normalized source path, then again after resolving through the deepest existing ancestor. Symlink-parent escapes do not bypass blocked-path or allowed-root checks.
+- Non-existent leaf paths are still checked safely. If `/workspace/alias-out/new-file` resolves through a symlinked parent to a blocked path or outside the configured allowed roots, the bind is rejected.
+- Binding `/var/run/docker.sock` effectively hands host control to the sandbox; only do this intentionally.
+- Workspace access (`workspaceAccess: "ro"`/`"rw"`) is independent of bind modes.
+
+## Tool policy: which tools exist/are callable
+
+Two layers matter:
+
+- **Tool profile**: `tools.profile` and `agents.list[].tools.profile` (base allowlist)
+- **Provider tool profile**: `tools.byProvider[provider].profile` and `agents.list[].tools.byProvider[provider].profile`
+- **Global/per-agent tool policy**: `tools.allow`/`tools.deny` and `agents.list[].tools.allow`/`agents.list[].tools.deny`
+- **Provider tool policy**: `tools.byProvider[provider].allow/deny` and `agents.list[].tools.byProvider[provider].allow/deny`
+- **Sandbox tool policy** (only applies when sandboxed): `tools.sandbox.tools.allow`/`tools.sandbox.tools.deny` and `agents.list[].tools.sandbox.tools.*`
+
+Rules of thumb:
+
+- `deny` always wins.
+- If `allow` is non-empty, everything else is treated as blocked.
+- Tool policy is the hard stop: `/exec` cannot override a denied `exec` tool.
+- `/exec` only changes session defaults for authorized senders; it does not grant tool access.
+  Provider tool keys accept either `provider` (e.g. `google-antigravity`) or `provider/model` (e.g. `openai/gpt-5.4`).
+
+### Tool groups (shorthands)
+
+Tool policies (global, agent, sandbox) support `group:*` entries that expand to multiple tools:
+
+```json5
+{
+  tools: {
+    sandbox: {
+      tools: {
+        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
+      },
+    },
+  },
+}
+```
+
+Available groups:
+
+- `group:runtime`: `exec`, `process`, `code_execution` (`bash` is accepted as
+  an alias for `exec`)
+- `group:fs`: `read`, `write`, `edit`, `apply_patch`
+- `group:sessions`: `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status`
+- `group:memory`: `memory_search`, `memory_get`
+- `group:web`: `web_search`, `x_search`, `web_fetch`
+- `group:ui`: `browser`, `canvas`
+- `group:automation`: `cron`, `gateway`
+- `group:messaging`: `message`
+- `group:nodes`: `nodes`
+- `group:agents`: `agents_list`
+- `group:media`: `image`, `image_generate`, `tts`
+- `group:Durar`: all built-in Durar tools (excludes provider plugins)
+
+## Elevated: exec-only "run on host"
+
+Elevated does **not** grant extra tools; it only affects `exec`.
+
+- If you’re sandboxed, `/elevated on` (or `exec` with `elevated: true`) runs outside the sandbox (approvals may still apply).
+- Use `/elevated full` to skip exec approvals for the session.
+- If you’re already running direct, elevated is effectively a no-op (still gated).
+- Elevated is **not** skill-scoped and does **not** override tool allow/deny.
+- Elevated does not grant arbitrary cross-host overrides from `host=auto`; it follows the normal exec target rules and only preserves `node` when the configured/session target is already `node`.
+- `/exec` is separate from elevated. It only adjusts per-session exec defaults for authorized senders.
+
+Gates:
+
+- Enablement: `tools.elevated.enabled` (and optionally `agents.list[].tools.elevated.enabled`)
+- Sender allowlists: `tools.elevated.allowFrom.<provider>` (and optionally `agents.list[].tools.elevated.allowFrom.<provider>`)
+
+See [Elevated Mode](/tools/elevated).
+
+## Common "sandbox jail" fixes
+
+### "Tool X blocked by sandbox tool policy"
+
+Fix-it keys (pick one):
+
+- Disable sandbox: `agents.defaults.sandbox.mode=off` (or per-agent `agents.list[].sandbox.mode=off`)
+- Allow the tool inside sandbox:
+  - remove it from `tools.sandbox.tools.deny` (or per-agent `agents.list[].tools.sandbox.tools.deny`)
+  - or add it to `tools.sandbox.tools.allow` (or per-agent allow)
+
+### "I thought this was main, why is it sandboxed?"
+
+In `"non-main"` mode, group/channel keys are _not_ main. Use the main session key (shown by `sandbox explain`) or switch mode to `"off"`.
+
+## See also
+
+- [Sandboxing](/gateway/sandboxing) -- full sandbox reference (modes, scopes, backends, images)
+- [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) -- per-agent overrides and precedence
+- [Elevated Mode](/tools/elevated)