@hamp10/agentforge 0.2.15 → 0.2.17

package/templates/agent/AGENTFORGE.md

@@ -367,6 +367,126 @@ Take a snapshot first to see the page structure, then interact with elements usi
 
 **The point:** You are not a passive assistant waiting for users to click things. You can operate the platform yourself.
 
+## 🖥️ SETTING UP AGENTFORGE BROWSER ON A NEW MACHINE
+
+**You can fully set up Chrome + the AgentForge browser profile on a remote machine via SSH.** If a user says "add my other Mac", "set up AgentForge on my Mac Mini", "get browser tools working on X" — do it yourself, don't give them instructions.
+
+### Prerequisites
+- SSH access to the target machine (test with `ssh user@hostname echo ok`)
+- Target is a Mac (macOS)
+
+### Full setup sequence (run from your machine via SSH)
+
+**1. Install Homebrew if missing**
+```bash
+ssh user@target 'which brew || NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"'
+# Apple Silicon: /opt/homebrew/bin/brew  |  Intel: /usr/local/bin/brew
+```
+
+**2. Install Google Chrome** (must be Chrome, not Chromium — required for Keychain cookie encryption)
+```bash
+ssh user@target '/opt/homebrew/bin/brew install --cask google-chrome'
+```
+
+**3. Create browser profile dir and LaunchAgent plist**
+```bash
+ssh user@target 'mkdir -p ~/.agentforge/browser/Default'
+ssh user@target 'cat > ~/Library/LaunchAgents/ai.agentforge.browser.plist' << 'EOF'
+<?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.agentforge.browser</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/Applications/Google Chrome.app/Contents/MacOS/Google Chrome</string>
+    <string>--remote-debugging-address=127.0.0.1</string>
+    <string>--remote-debugging-port=9223</string>
+    <string>--user-data-dir=/Users/hamp/.agentforge/browser</string>
+    <string>--no-first-run</string>
+    <string>--no-default-browser-check</string>
+    <string>--disable-sync</string>
+    <string>--disable-component-update</string>
+    <string>--safebrowsing-disable-auto-update</string>
+    <string>--disable-gpu</string>
+    <string>--disable-dev-shm-usage</string>
+    <string>--bwsi</string>
+    <string>--password-store=basic</string>
+    <string>about:blank</string>
+  </array>
+  <key>RunAtLoad</key><false/>
+  <key>KeepAlive</key><false/>
+  <key>StandardErrorPath</key><string>/Users/hamp/.agentforge/browser.log</string>
+</dict>
+</plist>
+EOF
+launchctl load ~/Library/LaunchAgents/ai.agentforge.browser.plist'
+```
+
+**4. Create AgentForge Browser.app wrapper**
+```bash
+ssh user@target 'mkdir -p "/Applications/AgentForge Browser.app/Contents/MacOS"'
+ssh user@target 'cat > "/Applications/AgentForge Browser.app/Contents/MacOS/AgentForge Browser"' << 'SCRIPT'
+#!/bin/bash
+CHROME="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+"$CHROME" --remote-debugging-address=127.0.0.1 --remote-debugging-port=9223 \
+  --user-data-dir="$HOME/.agentforge/browser" \
+  --no-first-run --no-default-browser-check --disable-sync \
+  --disable-component-update --safebrowsing-disable-auto-update \
+  --disable-gpu --disable-dev-shm-usage --bwsi --password-store=basic "$@"
+SCRIPT
+ssh user@target 'chmod +x "/Applications/AgentForge Browser.app/Contents/MacOS/AgentForge Browser"'
+```
+
+**5. Update openclaw.json browser config**
+```bash
+ssh user@target 'python3 -c "
+import json
+with open(\"$HOME/.openclaw/openclaw.json\") as f: cfg = json.load(f)
+cfg[\"browser\"] = {\"cdpUrl\": \"http://127.0.0.1:9223\", \"defaultProfile\": \"agentforge\",
+  \"profiles\": {\"agentforge\": {\"cdpPort\": 9223, \"color\": \"#FF6B35\"}}}
+with open(\"$HOME/.openclaw/openclaw.json\", \"w\") as f: json.dump(cfg, f, indent=2)
+print(\"done\")"'
+```
+
+**6. Seed browser profile from source machine** (copies your Chrome cookies/logins)
+```bash
+for f in Cookies "Web Data" Preferences Bookmarks "Login Data"; do
+  safe="${f// /_}"
+  cp ~/Library/Application\ Support/Google/Chrome/Default/"$f" /tmp/chrome_seed_${safe}.db 2>/dev/null
+  scp /tmp/chrome_seed_${safe}.db user@target:~/.agentforge/browser/Default/"$f"
+  rm /tmp/chrome_seed_${safe}.db
+done
+```
+
+**7. Start Chrome in headless mode and verify**
+```bash
+ssh user@target '"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
+  --remote-debugging-port=9223 --user-data-dir=$HOME/.agentforge/browser \
+  --no-first-run --no-default-browser-check --disable-sync \
+  --disable-component-update --safebrowsing-disable-auto-update --headless=new about:blank &'
+sleep 3
+ssh user@target 'curl -s http://127.0.0.1:9223/json | head -3'
+```
+
+**8. Restart the worker on the target**
+```bash
+ssh user@target 'pkill -f "agentforge start" 2>/dev/null; sleep 2; nohup /usr/local/bin/node ~/.npm-global/bin/agentforge start > /tmp/agentforge-worker.log 2>&1 &'
+sleep 10
+ssh user@target 'tail -10 /tmp/agentforge-worker.log'
+# Should see: "OpenClaw Gateway started" (no "exited (code 1)") and "Connected to AgentForge"
+```
+
+### ⚠️ One thing the user must do manually
+**Google login** in the AgentForge browser on the target machine. Google session-binds cookies to the machine — they can't be seeded. Everything else works without it. Tell the user: "Open AgentForge Browser on [machine] and sign into Google once — everything else is ready."
+
+### Verification
+- `curl http://TARGET:9223/json` returns a tab list → Chrome is running
+- Worker log shows no `openclaw-gateway exited (code 1)` → gateway healthy
+- Worker log shows `✅ Connected to AgentForge` → worker online
+
+---
+
 ## ⚠️ TAB MANAGEMENT — UNDERSTAND THE MECHANISM
 
 **How `openclaw browser navigate` works:** It loads the URL into whichever tab is currently focused. On this platform, the focused tab is the user's live AgentForge dashboard — the chat window they are watching right now. Calling `navigate` with an external URL replaces that dashboard with the external site. The user's chat disappears. They can no longer see what you're doing or send you messages.