loudmouth-ai 0.1.0

package/docs/platforms/macos.md

@@ -0,0 +1,195 @@
+---
+summary: "Clawdbot macOS companion app (menu bar + gateway broker)"
+read_when:
+  - Implementing macOS app features
+  - Changing gateway lifecycle or node bridging on macOS
+---
+# Clawdbot macOS Companion (menu bar + gateway broker)
+
+The macOS app is the **menu‑bar companion** for Clawdbot. 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 (`clawdbot`) 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 `clawdbot 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 `com.clawdbot.gateway`
+(or `com.clawdbot.<profile>` when using `--profile`/`CLAWDBOT_PROFILE`).
+
+```bash
+launchctl kickstart -k gui/$UID/com.clawdbot.gateway
+launchctl bootout gui/$UID/com.clawdbot.gateway
+```
+
+Replace the label with `com.clawdbot.<profile>` when running a named profile.
+
+If the LaunchAgent isn’t installed, enable it from the app or run
+`clawdbot 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:
+
+```
+~/.clawdbot/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 `clawdbot://` URL scheme for local actions.
+
+### `clawdbot://agent`
+
+Triggers a Gateway `agent` request.
+
+```bash
+open 'clawdbot://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.
+- With a valid `key`, the run is unattended (intended for personal automations).
+
+## Onboarding flow (typical)
+
+1) Install and launch **Clawdbot.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 Clawdbot` (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 clawdbot-mac connect --json
+swift run clawdbot-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 `clawdbot 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

@@ -0,0 +1,291 @@
+---
+summary: "Clawdbot on Oracle Cloud (Always Free ARM)"
+read_when:
+  - Setting up Clawdbot on Oracle Cloud
+  - Looking for low-cost VPS hosting for Clawdbot
+  - Want 24/7 Clawdbot on a small server
+---
+
+# Clawdbot on Oracle Cloud (OCI)
+
+## Goal
+
+Run a persistent Clawdbot Gateway on Oracle Cloud's **Always Free** ARM tier.
+
+Oracle’s free tier can be a great fit for Clawdbot (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:** `clawdbot`
+   - **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 clawdbot
+
+# 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=clawdbot
+```
+
+This enables Tailscale SSH, so you can connect via `ssh clawdbot` from any device on your tailnet — no public IP needed.
+
+Verify:
+```bash
+tailscale status
+```
+
+**From now on, connect via Tailscale:** `ssh ubuntu@clawdbot` (or use the Tailscale IP).
+
+## 5) Install Clawdbot
+
+```bash
+curl -fsSL https://clawd.bot/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
+clawdbot config set gateway.bind loopback
+
+# Require auth for the Gateway + Control UI
+clawdbot config set gateway.auth.mode token
+clawdbot doctor --generate-gateway-token
+
+# Expose over Tailscale Serve (HTTPS + tailnet access)
+clawdbot config set gateway.tailscale.mode serve
+clawdbot config set gateway.trustedProxies '["127.0.0.1"]'
+
+systemctl --user restart clawdbot-gateway
+```
+
+## 7) Verify
+
+```bash
+# Check version
+clawdbot --version
+
+# Check daemon status
+systemctl --user status clawdbot-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://clawdbot.<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 `clawdbot 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 ~/.clawdbot`
+- **Security audit:** `clawdbot 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@clawdbot
+```
+
+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=clawdbot --reset
+```
+
+### Gateway won't start
+```bash
+clawdbot gateway status
+clawdbot doctor --non-interactive
+journalctl --user -u clawdbot-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 clawdbot-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:
+- `~/.clawdbot/` — config, credentials, session data
+- `~/clawd/` — workspace (SOUL.md, memory, artifacts)
+
+Back up periodically:
+```bash
+tar -czvf clawdbot-backup.tar.gz ~/.clawdbot ~/clawd
+```
+
+---
+
+## 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](/platforms/hetzner) — Docker-based alternative