@ssdavidai/zoclaw 1.0.0

package/README.md

@@ -0,0 +1,79 @@
+# zoclaw
+
+Set up [OpenClaw](https://openclaw.ai) on a [Zo](https://zo.computer) instance with Tailscale access in one command.
+
+## Quick start
+
+On a fresh Zo instance:
+
+```bash
+npm install -g @ssdavidai/zoclaw && zoclaw init
+```
+
+Or via git:
+
+```bash
+git clone https://github.com/ssdavidai/zoclaw.git
+cd zoclaw
+./setup.sh
+```
+
+That's it. The setup script walks you through everything:
+
+1. Prompts for your Tailscale auth key (or uses the one already in zo secrets)
+2. Installs and configures Tailscale via [zotail](https://github.com/ssdavidai/zotail)
+3. Installs OpenClaw
+4. Runs the OpenClaw onboarding wizard
+5. Patches the config for secure Tailscale access
+6. Prints your Control UI URL and offers to launch the TUI
+
+### After setup
+
+On first browser load, the Control UI will request device pairing. Approve it once from the CLI:
+
+```bash
+openclaw devices list
+openclaw devices approve <request-id>
+```
+
+After that, the browser is permanently paired.
+
+## Why this exists
+
+After a fresh `openclaw configure` on Zo, the default gateway config doesn't work with Tailscale. You'll hit a series of issues:
+
+1. **"requires HTTPS or localhost"** -- Tailscale Serve terminates TLS externally and proxies to the gateway as plain HTTP on loopback. The gateway sees a localhost socket but a non-local `Host` header (your `.ts.net` hostname), so it treats the connection as remote and rejects it.
+
+2. **"device identity required"** -- The Control UI in the browser needs to complete device pairing, but the gateway doesn't recognize the browser as a trusted client without proper proxy configuration.
+
+3. **CLI pairing scope mismatch** -- The initial onboarding pairs the CLI with read-only scopes (`operator.read`), but the CLI needs full admin scopes (`operator.admin`, `operator.approvals`, `operator.pairing`) to function.
+
+4. **Security audit failures** -- The default config ships with invalid `denyCommands` entries and overly permissive credentials directory permissions.
+
+## What the bootstrap patches
+
+| Issue | Fix |
+|---|---|
+| Gateway doesn't trust Tailscale Serve | Sets `gateway.auth.allowTailscale: true` |
+| `.ts.net` Host header rejected as remote | Sets `gateway.trustedProxies: ["127.0.0.1/32"]` so the gateway trusts Tailscale Serve's forwarded headers |
+| Control UI not enabled | Sets `gateway.controlUi.enabled: true` |
+| CLI paired with read-only scopes | Upgrades paired device scopes to full admin |
+| Invalid `denyCommands` entries | Removes the ineffective default entries |
+| Credentials dir readable by others | `chmod 700 ~/.openclaw/credentials` |
+
+The script does **not** set `allowInsecureAuth` or `dangerouslyDisableDeviceAuth` -- those are insecure workarounds. Instead, it configures `trustedProxies` so the gateway properly recognizes Tailscale Serve connections as secure, and the browser goes through proper Ed25519 device pairing.
+
+## Scripts
+
+| Script | Purpose |
+|---|---|
+| `zoclaw init` | Full setup from scratch (Tailscale + OpenClaw + bootstrap) |
+| `zoclaw bootstrap` | Config patches only (if OpenClaw and Tailscale are already installed) |
+
+## Security
+
+Running `openclaw security audit` after setup should show **0 critical findings**. The setup uses `trustedProxies` + proper device pairing instead of insecure bypasses.
+
+## License
+
+MIT

package/bin/zoclaw.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+const { execFileSync } = require("child_process");
+const path = require("path");
+
+const command = process.argv[2];
+const scriptsDir = path.join(__dirname, "..", "scripts");
+
+const commands = {
+  init: "setup.sh",
+  bootstrap: "bootstrap.sh",
+};
+
+if (!command || !commands[command]) {
+  console.log("Usage: zoclaw <command>\n");
+  console.log("Commands:");
+  console.log("  init        Full setup (Tailscale + OpenClaw + bootstrap)");
+  console.log("  bootstrap   Config patches only (if already installed)");
+  process.exit(command ? 1 : 0);
+}
+
+const script = path.join(scriptsDir, commands[command]);
+
+try {
+  execFileSync("bash", [script], { stdio: "inherit" });
+} catch (err) {
+  process.exit(err.status ?? 1);
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@ssdavidai/zoclaw",
+  "version": "1.0.0",
+  "description": "Set up OpenClaw on Zo with Tailscale access in one command",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ssdavidai/zoclaw"
+  },
+  "bin": {
+    "zoclaw": "./bin/zoclaw.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "README.md"
+  ],
+  "keywords": [
+    "openclaw",
+    "zo",
+    "tailscale",
+    "zotail"
+  ]
+}

package/scripts/bootstrap.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# openclaw-tailscale-bootstrap.sh
+# Run AFTER: zotail is configured + `openclaw configure` has been run.
+# Patches the default openclaw config so the gateway is reachable
+# via Tailscale (both TUI and Control UI in browser).
+set -euo pipefail
+
+CONFIG="${HOME}/.openclaw/openclaw.json"
+PAIRED="${HOME}/.openclaw/devices/paired.json"
+PENDING="${HOME}/.openclaw/devices/pending.json"
+
+if [ ! -f "$CONFIG" ]; then
+  echo "Error: $CONFIG not found. Run 'openclaw configure' first."
+  exit 1
+fi
+
+echo "Patching openclaw config for Tailscale access..."
+
+# Patch gateway config
+node -e "
+  const fs = require('fs');
+  const cfg = JSON.parse(fs.readFileSync(process.argv[1], 'utf8'));
+  const gw = cfg.gateway ??= {};
+
+  // Trust Tailscale identity headers on serve connections
+  gw.auth ??= {};
+  gw.auth.allowTailscale = true;
+
+  // Enable control UI
+  gw.controlUi ??= {};
+  gw.controlUi.enabled = true;
+
+  // Remove invalid denyCommands entries (default config generates
+  // names that don't match real command IDs, triggering audit warnings)
+  if (gw.nodes?.denyCommands) delete gw.nodes.denyCommands;
+
+  // Trust localhost as a reverse proxy (Tailscale serve proxies
+  // HTTPS -> HTTP on loopback and forwards X-Forwarded-For).
+  // This lets the gateway recognize .ts.net Host headers as local.
+  gw.trustedProxies = ['127.0.0.1/32'];
+
+  // Fix credentials dir permissions
+  fs.chmodSync(process.env.HOME + '/.openclaw/credentials', 0o700);
+
+  fs.writeFileSync(process.argv[1], JSON.stringify(cfg, null, 2) + '\n');
+" "$CONFIG"
+
+echo "  gateway.auth.allowTailscale = true"
+echo "  gateway.controlUi.enabled = true"
+echo "  gateway.trustedProxies = [\"127.0.0.1/32\"]"
+echo "  nodes.denyCommands -> removed (invalid defaults)"
+echo "  credentials dir -> 700"
+
+# Upgrade any existing paired devices to full admin scopes
+if [ -f "$PAIRED" ]; then
+  node -e "
+    const fs = require('fs');
+    const paired = JSON.parse(fs.readFileSync(process.argv[1], 'utf8'));
+    const scopes = ['operator.read','operator.admin','operator.approvals','operator.pairing'];
+    for (const dev of Object.values(paired)) {
+      dev.clientId = 'cli';
+      dev.clientMode = 'cli';
+      dev.scopes = scopes;
+      for (const tok of Object.values(dev.tokens ?? {})) tok.scopes = scopes;
+    }
+    fs.writeFileSync(process.argv[1], JSON.stringify(paired, null, 2) + '\n');
+  " "$PAIRED"
+  echo "  Upgraded paired device scopes to full admin"
+fi
+
+# Clear stale pairing requests
+[ -f "$PENDING" ] && echo '{}' > "$PENDING"
+
+# Restart gateway
+echo "Restarting gateway..."
+pkill -f openclaw-gateway 2>/dev/null || true
+sleep 2
+openclaw gateway run --force > /dev/null 2>&1 &
+sleep 5
+
+# Verify
+if pgrep -f openclaw-gateway > /dev/null 2>&1; then
+  TOKEN=$(node -pe "JSON.parse(require('fs').readFileSync('${CONFIG}','utf8')).gateway?.auth?.token ?? ''")
+  TS_URL=$(tailscale serve status 2>/dev/null | grep -oP 'https://\S+' | head -1 || true)
+
+  echo ""
+  echo "Ready!"
+  echo "  TUI:     openclaw tui"
+  if [ -n "$TS_URL" ] && [ -n "$TOKEN" ]; then
+    echo "  Browser: ${TS_URL}?token=${TOKEN}"
+    echo ""
+    echo "  On first browser load, the Control UI will request device pairing."
+    echo "  Approve it from the TUI or CLI:"
+    echo "    openclaw devices list"
+    echo "    openclaw devices approve <request-id>"
+  fi
+else
+  echo "Warning: gateway did not start. Check 'openclaw gateway run --force' manually."
+fi

package/scripts/setup.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+# setup.sh — Full OpenClaw + Tailscale setup for Zo
+# Installs everything from scratch on a fresh Zo instance.
+set -euo pipefail
+
+SECRETS_FILE="${HOME}/.zo_secrets"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BOOTSTRAP="${SCRIPT_DIR}/bootstrap.sh"
+
+# ─── Helpers ──────────────────────────────────────────────────────────
+
+step() { echo -e "\n\033[1;36m[$1/5]\033[0m \033[1m$2\033[0m"; }
+
+ensure_secrets_file() {
+  if [ ! -f "$SECRETS_FILE" ]; then
+    touch "$SECRETS_FILE"
+    chmod 600 "$SECRETS_FILE"
+  fi
+}
+
+# ─── Step 1: Tailscale auth key ──────────────────────────────────────
+
+step 1 "Tailscale auth key"
+
+ensure_secrets_file
+source "$SECRETS_FILE" 2>/dev/null || true
+
+if [ -n "${TAILSCALE_AUTH_KEY:-}" ]; then
+  echo "  Found TAILSCALE_AUTH_KEY in zo secrets, using existing key."
+else
+  echo "  No TAILSCALE_AUTH_KEY found in zo secrets."
+  echo "  Generate one at: https://login.tailscale.com/admin/settings/keys"
+  echo ""
+  read -rp "  Enter your Tailscale auth key: " ts_key
+  if [ -z "$ts_key" ]; then
+    echo "  Error: auth key cannot be empty."
+    exit 1
+  fi
+  echo "export TAILSCALE_AUTH_KEY=\"${ts_key}\"" >> "$SECRETS_FILE"
+  export TAILSCALE_AUTH_KEY="$ts_key"
+  echo "  Saved to zo secrets."
+fi
+
+# ─── Step 2: Install and configure Tailscale via zotail ──────────────
+
+step 2 "Tailscale (zotail)"
+
+echo "  Installing zotail..."
+npm install -g @ssdavidai/zotail 2>&1 | tail -1
+
+echo "  Running zotail setup..."
+zotail setup
+
+# ─── Step 3: Install OpenClaw ────────────────────────────────────────
+
+step 3 "OpenClaw"
+
+echo "  Installing openclaw..."
+npm install -g openclaw@latest 2>&1 | tail -1
+
+# ─── Step 4: OpenClaw onboarding ─────────────────────────────────────
+
+step 4 "OpenClaw onboarding"
+
+echo "  Running interactive setup..."
+echo "  (When the onboarding finishes, setup will continue automatically.)"
+echo ""
+openclaw onboard --install-daemon
+
+# ─── Step 5: Bootstrap Tailscale config ──────────────────────────────
+
+step 5 "Tailscale bootstrap"
+
+if [ ! -f "$BOOTSTRAP" ]; then
+  echo "  Error: bootstrap.sh not found at ${BOOTSTRAP}"
+  exit 1
+fi
+
+bash "$BOOTSTRAP"
+
+# ─── Done ────────────────────────────────────────────────────────────
+
+CONFIG="${HOME}/.openclaw/openclaw.json"
+TOKEN=$(node -pe "JSON.parse(require('fs').readFileSync('${CONFIG}','utf8')).gateway?.auth?.token ?? ''" 2>/dev/null || true)
+TS_URL=$(tailscale serve status 2>/dev/null | grep -oP 'https://\S+' | head -1 || true)
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "  Setup complete!"
+echo ""
+if [ -n "$TS_URL" ] && [ -n "$TOKEN" ]; then
+  echo "  Control UI: ${TS_URL}?token=${TOKEN}"
+  echo ""
+  echo "  (On first browser load, approve device pairing from the CLI:"
+  echo "   openclaw devices list && openclaw devices approve <id>)"
+fi
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+read -rp "  Launch the TUI now? [Y/n] " launch_tui
+launch_tui="${launch_tui:-Y}"
+
+if [[ "$launch_tui" =~ ^[Yy]$ ]]; then
+  exec openclaw tui
+else
+  echo "  Run 'openclaw tui' whenever you're ready."
+fi