@symerian/symi 3.0.20 → 3.0.22

package/docs/platforms/macos.md

@@ -1,204 +0,0 @@
----
-summary: "Symi macOS companion app (menu bar + gateway broker)"
-read_when:
-  - Implementing macOS app features
-  - Changing gateway lifecycle or node bridging on macOS
-title: "macOS App"
----
-
-# Symi macOS Companion (menu bar + gateway broker)
-
-The macOS app is the **menu‑bar companion** for Symi. It owns permissions,
-manages/attaches to the Gateway locally (launchd or manual), and exposes macOS
-capabilities to the agent as a node.
-
-## What it does
-
-- Shows native notifications and status in the menu bar.
-- Owns TCC prompts (Notifications, Accessibility, Screen Recording, Microphone,
-  Speech Recognition, Automation/AppleScript).
-- Runs or connects to the Gateway (local or remote).
-- Exposes macOS‑only tools (Canvas, Camera, Screen Recording, `system.run`).
-- Starts the local node host service in **remote** mode (launchd), and stops it in **local** mode.
-- Optionally hosts **PeekabooBridge** for UI automation.
-- Installs the global CLI (`symi`) via npm/pnpm on request (bun not recommended for the Gateway runtime).
-
-## Local vs remote mode
-
-- **Local** (default): the app attaches to a running local Gateway if present;
-  otherwise it enables the launchd service via `symi gateway install`.
-- **Remote**: the app connects to a Gateway over SSH/Tailscale and never starts
-  a local process.
-  The app starts the local **node host service** so the remote Gateway can reach this Mac.
-  The app does not spawn the Gateway as a child process.
-
-## Launchd control
-
-The app manages a per‑user LaunchAgent labeled `bot.molt.gateway`
-(or `bot.molt.<profile>` when using `--profile`/`SYMI_PROFILE`; legacy `com.symi.*` still unloads).
-
-```bash
-launchctl kickstart -k gui/$UID/bot.molt.gateway
-launchctl bootout gui/$UID/bot.molt.gateway
-```
-
-Replace the label with `bot.molt.<profile>` when running a named profile.
-
-If the LaunchAgent isn’t installed, enable it from the app or run
-`symi gateway install`.
-
-## Node capabilities (mac)
-
-The macOS app presents itself as a node. Common commands:
-
-- Canvas: `canvas.present`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`, `canvas.a2ui.*`
-- Camera: `camera.snap`, `camera.clip`
-- Screen: `screen.record`
-- System: `system.run`, `system.notify`
-
-The node reports a `permissions` map so agents can decide what’s allowed.
-
-Node service + app IPC:
-
-- When the headless node host service is running (remote mode), it connects to the Gateway WS as a node.
-- `system.run` executes in the macOS app (UI/TCC context) over a local Unix socket; prompts + output stay in-app.
-
-Diagram (SCI):
-
-```
-Gateway -> Node Service (WS)
-                 |  IPC (UDS + token + HMAC + TTL)
-                 v
-             Mac App (UI + TCC + system.run)
-```
-
-## Exec approvals (system.run)
-
-`system.run` is controlled by **Exec approvals** in the macOS app (Settings → Exec approvals).
-Security + ask + allowlist are stored locally on the Mac in:
-
-```
-~/.symi/exec-approvals.json
-```
-
-Example:
-
-```json
-{
-  "version": 1,
-  "defaults": {
-    "security": "deny",
-    "ask": "on-miss"
-  },
-  "agents": {
-    "main": {
-      "security": "allowlist",
-      "ask": "on-miss",
-      "allowlist": [{ "pattern": "/opt/homebrew/bin/rg" }]
-    }
-  }
-}
-```
-
-Notes:
-
-- `allowlist` entries are glob patterns for resolved binary paths.
-- Choosing “Always Allow” in the prompt adds that command to the allowlist.
-- `system.run` environment overrides are filtered (drops `PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`) and then merged with the app’s environment.
-
-## Deep links
-
-The app registers the `symi://` URL scheme for local actions.
-
-### `symi://agent`
-
-Triggers a Gateway `agent` request.
-
-```bash
-open 'symi://agent?message=Hello%20from%20deep%20link'
-```
-
-Query parameters:
-
-- `message` (required)
-- `sessionKey` (optional)
-- `thinking` (optional)
-- `deliver` / `to` / `channel` (optional)
-- `timeoutSeconds` (optional)
-- `key` (optional unattended mode key)
-
-Safety:
-
-- Without `key`, the app prompts for confirmation.
-- Without `key`, the app enforces a short message limit for the confirmation prompt and ignores `deliver` / `to` / `channel`.
-- With a valid `key`, the run is unattended (intended for personal automations).
-
-## Onboarding flow (typical)
-
-1. Install and launch **Symi.app**.
-2. Complete the permissions checklist (TCC prompts).
-3. Ensure **Local** mode is active and the Gateway is running.
-4. Install the CLI if you want terminal access.
-
-## Build & dev workflow (native)
-
-- `cd apps/macos && swift build`
-- `swift run Symi` (or Xcode)
-- Package app: `scripts/package-mac-app.sh`
-
-## Debug gateway connectivity (macOS CLI)
-
-Use the debug CLI to exercise the same Gateway WebSocket handshake and discovery
-logic that the macOS app uses, without launching the app.
-
-```bash
-cd apps/macos
-swift run symi-mac connect --json
-swift run symi-mac discover --timeout 3000 --json
-```
-
-Connect options:
-
-- `--url <ws://host:port>`: override config
-- `--mode <local|remote>`: resolve from config (default: config or local)
-- `--probe`: force a fresh health probe
-- `--timeout <ms>`: request timeout (default: `15000`)
-- `--json`: structured output for diffing
-
-Discovery options:
-
-- `--include-local`: include gateways that would be filtered as “local”
-- `--timeout <ms>`: overall discovery window (default: `2000`)
-- `--json`: structured output for diffing
-
-Tip: compare against `symi gateway discover --json` to see whether the
-macOS app’s discovery pipeline (NWBrowser + tailnet DNS‑SD fallback) differs from
-the Node CLI’s `dns-sd` based discovery.
-
-## Remote connection plumbing (SSH tunnels)
-
-When the macOS app runs in **Remote** mode, it opens an SSH tunnel so local UI
-components can talk to a remote Gateway as if it were on localhost.
-
-### Control tunnel (Gateway WebSocket port)
-
-- **Purpose:** health checks, status, Web Chat, config, and other control-plane calls.
-- **Local port:** the Gateway port (default `18789`), always stable.
-- **Remote port:** the same Gateway port on the remote host.
-- **Behavior:** no random local port; the app reuses an existing healthy tunnel
-  or restarts it if needed.
-- **SSH shape:** `ssh -N -L <local>:127.0.0.1:<remote>` with BatchMode +
-  ExitOnForwardFailure + keepalive options.
-- **IP reporting:** the SSH tunnel uses loopback, so the gateway will see the node
-  IP as `127.0.0.1`. Use **Direct (ws/wss)** transport if you want the real client
-  IP to appear (see [macOS remote access](/platforms/mac/remote)).
-
-For setup steps, see [macOS remote access](/platforms/mac/remote). For protocol
-details, see [Gateway protocol](/gateway/protocol).
-
-## Related docs
-
-- [Gateway runbook](/gateway)
-- [Gateway (macOS)](/platforms/mac/bundled-gateway)
-- [macOS permissions](/platforms/mac/permissions)
-- [Canvas](/platforms/mac/canvas)

package/docs/platforms/oracle.md

@@ -1,303 +0,0 @@
----
-summary: "Symi on Oracle Cloud (Always Free ARM)"
-read_when:
-  - Setting up Symi on Oracle Cloud
-  - Looking for low-cost VPS hosting for Symi
-  - Want 24/7 Symi on a small server
-title: "Oracle Cloud"
----
-
-# Symi on Oracle Cloud (OCI)
-
-## Goal
-
-Run a persistent Symi Gateway on Oracle Cloud's **Always Free** ARM tier.
-
-Oracle’s free tier can be a great fit for Symi (especially if you already have an OCI account), but it comes with tradeoffs:
-
-- ARM architecture (most things work, but some binaries may be x86-only)
-- Capacity and signup can be finicky
-
-## Cost Comparison (2026)
-
-| Provider     | Plan            | Specs                  | Price/mo | Notes                 |
-| ------------ | --------------- | ---------------------- | -------- | --------------------- |
-| Oracle Cloud | Always Free ARM | up to 4 OCPU, 24GB RAM | $0       | ARM, limited capacity |
-| Hetzner      | CX22            | 2 vCPU, 4GB RAM        | ~ $4     | Cheapest paid option  |
-| DigitalOcean | Basic           | 1 vCPU, 1GB RAM        | $6       | Easy UI, good docs    |
-| Vultr        | Cloud Compute   | 1 vCPU, 1GB RAM        | $6       | Many locations        |
-| Linode       | Nanode          | 1 vCPU, 1GB RAM        | $5       | Now part of Akamai    |
-
----
-
-## Prerequisites
-
-- Oracle Cloud account ([signup](https://www.oracle.com/cloud/free/)) — see [community signup guide](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd) if you hit issues
-- Tailscale account (free at [tailscale.com](https://tailscale.com))
-- ~30 minutes
-
-## 1) Create an OCI Instance
-
-1. Log into [Oracle Cloud Console](https://cloud.oracle.com/)
-2. Navigate to **Compute → Instances → Create Instance**
-3. Configure:
-   - **Name:** `symi`
-   - **Image:** Ubuntu 24.04 (aarch64)
-   - **Shape:** `VM.Standard.A1.Flex` (Ampere ARM)
-   - **OCPUs:** 2 (or up to 4)
-   - **Memory:** 12 GB (or up to 24 GB)
-   - **Boot volume:** 50 GB (up to 200 GB free)
-   - **SSH key:** Add your public key
-4. Click **Create**
-5. Note the public IP address
-
-**Tip:** If instance creation fails with "Out of capacity", try a different availability domain or retry later. Free tier capacity is limited.
-
-## 2) Connect and Update
-
-```bash
-# Connect via public IP
-ssh ubuntu@YOUR_PUBLIC_IP
-
-# Update system
-sudo apt update && sudo apt upgrade -y
-sudo apt install -y build-essential
-```
-
-**Note:** `build-essential` is required for ARM compilation of some dependencies.
-
-## 3) Configure User and Hostname
-
-```bash
-# Set hostname
-sudo hostnamectl set-hostname symi
-
-# Set password for ubuntu user
-sudo passwd ubuntu
-
-# Enable lingering (keeps user services running after logout)
-sudo loginctl enable-linger ubuntu
-```
-
-## 4) Install Tailscale
-
-```bash
-curl -fsSL https://tailscale.com/install.sh | sh
-sudo tailscale up --ssh --hostname=symi
-```
-
-This enables Tailscale SSH, so you can connect via `ssh symi` from any device on your tailnet — no public IP needed.
-
-Verify:
-
-```bash
-tailscale status
-```
-
-**From now on, connect via Tailscale:** `ssh ubuntu@symi` (or use the Tailscale IP).
-
-## 5) Install Symi
-
-```bash
-curl -fsSL https://jaysteelmind.github.io/getsymi/install.sh | bash
-source ~/.bashrc
-```
-
-When prompted "How do you want to hatch your bot?", select **"Do this later"**.
-
-> Note: If you hit ARM-native build issues, start with system packages (e.g. `sudo apt install -y build-essential`) before reaching for Homebrew.
-
-## 6) Configure Gateway (loopback + token auth) and enable Tailscale Serve
-
-Use token auth as the default. It’s predictable and avoids needing any “insecure auth” Control UI flags.
-
-```bash
-# Keep the Gateway private on the VM
-symi config set gateway.bind loopback
-
-# Require auth for the Gateway + Control UI
-symi config set gateway.auth.mode token
-symi doctor --generate-gateway-token
-
-# Expose over Tailscale Serve (HTTPS + tailnet access)
-symi config set gateway.tailscale.mode serve
-symi config set gateway.trustedProxies '["127.0.0.1"]'
-
-systemctl --user restart symi-gateway
-```
-
-## 7) Verify
-
-```bash
-# Check version
-symi --version
-
-# Check daemon status
-systemctl --user status symi-gateway
-
-# Check Tailscale Serve
-tailscale serve status
-
-# Test local response
-curl http://localhost:18789
-```
-
-## 8) Lock Down VCN Security
-
-Now that everything is working, lock down the VCN to block all traffic except Tailscale. OCI's Virtual Cloud Network acts as a firewall at the network edge — traffic is blocked before it reaches your instance.
-
-1. Go to **Networking → Virtual Cloud Networks** in the OCI Console
-2. Click your VCN → **Security Lists** → Default Security List
-3. **Remove** all ingress rules except:
-   - `0.0.0.0/0 UDP 41641` (Tailscale)
-4. Keep default egress rules (allow all outbound)
-
-This blocks SSH on port 22, HTTP, HTTPS, and everything else at the network edge. From now on, you can only connect via Tailscale.
-
----
-
-## Access the Control UI
-
-From any device on your Tailscale network:
-
-```
-https://symi.<tailnet-name>.ts.net/
-```
-
-Replace `<tailnet-name>` with your tailnet name (visible in `tailscale status`).
-
-No SSH tunnel needed. Tailscale provides:
-
-- HTTPS encryption (automatic certs)
-- Authentication via Tailscale identity
-- Access from any device on your tailnet (laptop, phone, etc.)
-
----
-
-## Security: VCN + Tailscale (recommended baseline)
-
-With the VCN locked down (only UDP 41641 open) and the Gateway bound to loopback, you get strong defense-in-depth: public traffic is blocked at the network edge, and admin access happens over your tailnet.
-
-This setup often removes the _need_ for extra host-based firewall rules purely to stop Internet-wide SSH brute force — but you should still keep the OS updated, run `symi security audit`, and verify you aren’t accidentally listening on public interfaces.
-
-### What's Already Protected
-
-| Traditional Step   | Needed?     | Why                                                                          |
-| ------------------ | ----------- | ---------------------------------------------------------------------------- |
-| UFW firewall       | No          | VCN blocks before traffic reaches instance                                   |
-| fail2ban           | No          | No brute force if port 22 blocked at VCN                                     |
-| sshd hardening     | No          | Tailscale SSH doesn't use sshd                                               |
-| Disable root login | No          | Tailscale uses Tailscale identity, not system users                          |
-| SSH key-only auth  | No          | Tailscale authenticates via your tailnet                                     |
-| IPv6 hardening     | Usually not | Depends on your VCN/subnet settings; verify what’s actually assigned/exposed |
-
-### Still Recommended
-
-- **Credential permissions:** `chmod 700 ~/.symi`
-- **Security audit:** `symi security audit`
-- **System updates:** `sudo apt update && sudo apt upgrade` regularly
-- **Monitor Tailscale:** Review devices in [Tailscale admin console](https://login.tailscale.com/admin)
-
-### Verify Security Posture
-
-```bash
-# Confirm no public ports listening
-sudo ss -tlnp | grep -v '127.0.0.1\|::1'
-
-# Verify Tailscale SSH is active
-tailscale status | grep -q 'offers: ssh' && echo "Tailscale SSH active"
-
-# Optional: disable sshd entirely
-sudo systemctl disable --now ssh
-```
-
----
-
-## Fallback: SSH Tunnel
-
-If Tailscale Serve isn't working, use an SSH tunnel:
-
-```bash
-# From your local machine (via Tailscale)
-ssh -L 18789:127.0.0.1:18789 ubuntu@symi
-```
-
-Then open `http://localhost:18789`.
-
----
-
-## Troubleshooting
-
-### Instance creation fails ("Out of capacity")
-
-Free tier ARM instances are popular. Try:
-
-- Different availability domain
-- Retry during off-peak hours (early morning)
-- Use the "Always Free" filter when selecting shape
-
-### Tailscale won't connect
-
-```bash
-# Check status
-sudo tailscale status
-
-# Re-authenticate
-sudo tailscale up --ssh --hostname=symi --reset
-```
-
-### Gateway won't start
-
-```bash
-symi gateway status
-symi doctor --non-interactive
-journalctl --user -u symi-gateway -n 50
-```
-
-### Can't reach Control UI
-
-```bash
-# Verify Tailscale Serve is running
-tailscale serve status
-
-# Check gateway is listening
-curl http://localhost:18789
-
-# Restart if needed
-systemctl --user restart symi-gateway
-```
-
-### ARM binary issues
-
-Some tools may not have ARM builds. Check:
-
-```bash
-uname -m  # Should show aarch64
-```
-
-Most npm packages work fine. For binaries, look for `linux-arm64` or `aarch64` releases.
-
----
-
-## Persistence
-
-All state lives in:
-
-- `~/.symi/` — config, credentials, session data
-- `~/.symi/workspace/` — workspace (SYMICORE.md, memory, artifacts)
-
-Back up periodically:
-
-```bash
-tar -czvf symi-backup.tar.gz ~/.symi ~/.symi/workspace
-```
-
----
-
-## See Also
-
-- [Gateway remote access](/gateway/remote) — other remote access patterns
-- [Tailscale integration](/gateway/tailscale) — full Tailscale docs
-- [Gateway configuration](/gateway/configuration) — all config options
-- [DigitalOcean guide](/platforms/digitalocean) — if you want paid + easier signup
-- [Hetzner guide](/install/hetzner) — Docker-based alternative