@symerian/symi 3.0.20 → 3.0.22

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

@@ -1,158 +0,0 @@
----
-summary: "SSH tunnel setup for Symi.app connecting to a remote gateway"
-read_when: "Connecting the macOS app to a remote gateway over SSH"
-title: "Remote Gateway Setup"
----
-
-# Running Symi.app with a Remote Gateway
-
-Symi.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["Symi.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: Set Gateway Token
-
-```bash
-launchctl setenv SYMI_GATEWAY_TOKEN "<your-token>"
-```
-
-### Step 4: Start SSH Tunnel
-
-```bash
-ssh -N remote-gateway &
-```
-
-### Step 5: Restart Symi.app
-
-```bash
-# Quit Symi.app (⌘Q), then reopen:
-open /path/to/Symi.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/bot.molt.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>bot.molt.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/bot.molt.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.symi.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/bot.molt.ssh-tunnel
-```
-
-**Stop the tunnel:**
-
-```bash
-launchctl bootout gui/$UID/bot.molt.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                           |
-
-Symi.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

@@ -1,131 +0,0 @@
----
-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 → “Symi 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:
-
-- `symi health` and `symi status --deep` now reach the remote gateway via `ws://127.0.0.1:18789`.
-- `symi gateway {status,health,send,agent,call}` can also target the forwarded URL via `--url` when needed.
-
-Note: replace `18789` with your configured `gateway.port` (or `--port`/`SYMI_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.
-
-## 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).
-- **Non-loopback binds** (`lan`/`tailnet`/`custom`, or `auto` when loopback is unavailable) must use auth tokens/passwords.
-- `gateway.remote.token` is **only** for remote CLI calls — it does **not** enable local auth.
-- `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 still
-  require token/password auth. This tokenless flow assumes the gateway host is
-  trusted. Set it to `false` if you want tokens/passwords everywhere.
-- Treat browser control like operator access: tailnet-only + deliberate node pairing.
-
-Deep dive: [Security](/gateway/security).

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

@@ -1,128 +0,0 @@
----
-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
-
-Symi 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 on the host when you’re sandboxed.
-
-## Quick debug
-
-Use the inspector to see what Symi is _actually_ doing:
-
-```bash
-symi sandbox explain
-symi sandbox explain --session agent:main:main
-symi sandbox explain --agent work
-symi 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).
-- 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.2`).
-
-### 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`, `bash`, `process`
-- `group:fs`: `read`, `write`, `edit`, `apply_patch`
-- `group:sessions`: `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `session_status`
-- `group:memory`: `memory_search`, `memory_get`
-- `group:ui`: `browser`, `canvas`
-- `group:automation`: `cron`, `gateway`
-- `group:messaging`: `message`
-- `group:nodes`: `nodes`
-- `group:symi`: all built-in Symi 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 on the host (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.
-- `/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"`.

package/docs/gateway/sandboxing.md

@@ -1,203 +0,0 @@
----
-summary: "How Symi sandboxing works: modes, scopes, workspace access, and images"
-title: Sandboxing
-read_when: "You want a dedicated explanation of sandboxing or need to tune agents.defaults.sandbox."
-status: active
----
-
-# Sandboxing
-
-Symi can run **tools inside Docker containers** to reduce blast radius.
-This is **optional** and controlled by configuration (`agents.defaults.sandbox` or
-`agents.list[].sandbox`). If sandboxing is off, tools run on the host.
-The Gateway stays on the host; tool execution runs in an isolated sandbox
-when enabled.
-
-This is not a perfect security boundary, but it materially limits filesystem
-and process access when the model does something dumb.
-
-## What gets sandboxed
-
-- Tool execution (`exec`, `read`, `write`, `edit`, `apply_patch`, `process`, etc.).
-- Optional sandboxed browser (`agents.defaults.sandbox.browser`).
-  - By default, the sandbox browser auto-starts (ensures CDP is reachable) when the browser tool needs it.
-    Configure via `agents.defaults.sandbox.browser.autoStart` and `agents.defaults.sandbox.browser.autoStartTimeoutMs`.
-  - By default, sandbox browser containers use a dedicated Docker network (`symi-sandbox-browser`) instead of the global `bridge` network.
-    Configure with `agents.defaults.sandbox.browser.network`.
-  - Optional `agents.defaults.sandbox.browser.cdpSourceRange` restricts container-edge CDP ingress with a CIDR allowlist (for example `172.21.0.1/32`).
-  - noVNC observer access is password-protected by default; Symi emits a short-lived token URL that resolves to the observer session.
-  - `agents.defaults.sandbox.browser.allowHostControl` lets sandboxed sessions target the host browser explicitly.
-  - Optional allowlists gate `target: "custom"`: `allowedControlUrls`, `allowedControlHosts`, `allowedControlPorts`.
-
-Not sandboxed:
-
-- The Gateway process itself.
-- Any tool explicitly allowed to run on the host (e.g. `tools.elevated`).
-  - **Elevated exec runs on the host and bypasses sandboxing.**
-  - If sandboxing is off, `tools.elevated` does not change execution (already on host). See [Elevated Mode](/tools/elevated).
-
-## Modes
-
-`agents.defaults.sandbox.mode` controls **when** sandboxing is used:
-
-- `"off"`: no sandboxing.
-- `"non-main"`: sandbox only **non-main** sessions (default if you want normal chats on host).
-- `"all"`: every session runs in a sandbox.
-  Note: `"non-main"` is based on `session.mainKey` (default `"main"`), not agent id.
-  Group/channel sessions use their own keys, so they count as non-main and will be sandboxed.
-
-## Scope
-
-`agents.defaults.sandbox.scope` controls **how many containers** are created:
-
-- `"session"` (default): one container per session.
-- `"agent"`: one container per agent.
-- `"shared"`: one container shared by all sandboxed sessions.
-
-## Workspace access
-
-`agents.defaults.sandbox.workspaceAccess` controls **what the sandbox can see**:
-
-- `"none"` (default): tools see a sandbox workspace under `~/.symi/sandboxes`.
-- `"ro"`: mounts the agent workspace read-only at `/agent` (disables `write`/`edit`/`apply_patch`).
-- `"rw"`: mounts the agent workspace read/write at `/workspace`.
-
-Inbound media is copied into the active sandbox workspace (`media/inbound/*`).
-Skills note: the `read` tool is sandbox-rooted. With `workspaceAccess: "none"`,
-Symi mirrors eligible skills into the sandbox workspace (`.../skills`) so
-they can be read. With `"rw"`, workspace skills are readable from
-`/workspace/skills`.
-
-## Custom bind mounts
-
-`agents.defaults.sandbox.docker.binds` mounts additional host directories into the container.
-Format: `host:container:mode` (e.g., `"/home/user/source:/source:rw"`).
-
-Global and per-agent binds are **merged** (not replaced). Under `scope: "shared"`, per-agent binds are ignored.
-
-`agents.defaults.sandbox.browser.binds` mounts additional host directories into the **sandbox browser** container only.
-
-- When set (including `[]`), it replaces `agents.defaults.sandbox.docker.binds` for the browser container.
-- When omitted, the browser container falls back to `agents.defaults.sandbox.docker.binds` (backwards compatible).
-
-Example (read-only source + an extra data directory):
-
-```json5
-{
-  agents: {
-    defaults: {
-      sandbox: {
-        docker: {
-          binds: ["/home/user/source:/source:ro", "/var/data/myapp:/data:ro"],
-        },
-      },
-    },
-    list: [
-      {
-        id: "build",
-        sandbox: {
-          docker: {
-            binds: ["/mnt/cache:/cache:rw"],
-          },
-        },
-      },
-    ],
-  },
-}
-```
-
-Security notes:
-
-- Binds bypass the sandbox filesystem: they expose host paths with whatever mode you set (`:ro` or `:rw`).
-- Symi blocks dangerous bind sources (for example: `docker.sock`, `/etc`, `/proc`, `/sys`, `/dev`, and parent mounts that would expose them).
-- Sensitive mounts (secrets, SSH keys, service credentials) should be `:ro` unless absolutely required.
-- Combine with `workspaceAccess: "ro"` if you only need read access to the workspace; bind modes stay independent.
-- See [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) for how binds interact with tool policy and elevated exec.
-
-## Images + setup
-
-Default image: `symi-sandbox:bookworm-slim`
-
-Build it once:
-
-```bash
-scripts/sandbox-setup.sh
-```
-
-Note: the default image does **not** include Node. If a skill needs Node (or
-other runtimes), either bake a custom image or install via
-`sandbox.docker.setupCommand` (requires network egress + writable root +
-root user).
-
-Sandboxed browser image:
-
-```bash
-scripts/sandbox-browser-setup.sh
-```
-
-By default, sandbox containers run with **no network**.
-Override with `agents.defaults.sandbox.docker.network`.
-
-Docker installs and the containerized gateway live here:
-[Docker](/install/docker)
-
-## setupCommand (one-time container setup)
-
-`setupCommand` runs **once** after the sandbox container is created (not on every run).
-It executes inside the container via `sh -lc`.
-
-Paths:
-
-- Global: `agents.defaults.sandbox.docker.setupCommand`
-- Per-agent: `agents.list[].sandbox.docker.setupCommand`
-
-Common pitfalls:
-
-- Default `docker.network` is `"none"` (no egress), so package installs will fail.
-- `readOnlyRoot: true` prevents writes; set `readOnlyRoot: false` or bake a custom image.
-- `user` must be root for package installs (omit `user` or set `user: "0:0"`).
-- Sandbox exec does **not** inherit host `process.env`. Use
-  `agents.defaults.sandbox.docker.env` (or a custom image) for skill API keys.
-
-## Tool policy + escape hatches
-
-Tool allow/deny policies still apply before sandbox rules. If a tool is denied
-globally or per-agent, sandboxing doesn’t bring it back.
-
-`tools.elevated` is an explicit escape hatch that runs `exec` on the host.
-`/exec` directives only apply for authorized senders and persist per session; to hard-disable
-`exec`, use tool policy deny (see [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated)).
-
-Debugging:
-
-- Use `symi sandbox explain` to inspect effective sandbox mode, tool policy, and fix-it config keys.
-- See [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) for the “why is this blocked?” mental model.
-  Keep it locked down.
-
-## Multi-agent overrides
-
-Each agent can override sandbox + tools:
-`agents.list[].sandbox` and `agents.list[].tools` (plus `agents.list[].tools.sandbox.tools` for sandbox tool policy).
-See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for precedence.
-
-## Minimal enable example
-
-```json5
-{
-  agents: {
-    defaults: {
-      sandbox: {
-        mode: "non-main",
-        scope: "session",
-        workspaceAccess: "none",
-      },
-    },
-  },
-}
-```
-
-## Related docs
-
-- [Sandbox Configuration](/gateway/configuration#agentsdefaults-sandbox)
-- [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools)
-- [Security](/gateway/security)