@ssdavidai/zoclaw 1.3.0-next.6 → 1.3.0

package/README.md

@@ -1,78 +1,92 @@
 # zoclaw
 
-Set up [OpenClaw](https://openclaw.ai) on a [Zo](https://zo.computer) instance with Tailscale access in one command.
+Run AI agents on your [Zo](https://zo.computer) machine and control them from anywhere on your private network.
 
-## Quick start
+zoclaw connects [OpenClaw](https://openclaw.ai) (an open-source AI agent platform) to [Tailscale](https://tailscale.com) (a private mesh VPN) on a Zo machine. After setup, you get:
 
-On a fresh Zo instance:
+- **A terminal UI** to chat with your AI agent over SSH or directly on the machine
+- **A browser Control UI** accessible from any device on your tailnet (laptop, phone, tablet) — no port forwarding, no public exposure
+- **A supervised gateway** that auto-restarts on crash or container reboot
+- **Zo-native secrets management** — API keys and tokens stored in `/root/.zo_secrets`, not scattered across config files
 
-```bash
-npm install -g @ssdavidai/zoclaw && zoclaw init
-```
-
-Or via git:
+## Quick start
 
 ```bash
-git clone https://github.com/ssdavidai/zoclaw.git
-cd zoclaw
-./setup.sh
+npm install -g @ssdavidai/zoclaw
+zoclaw init
 ```
 
-That's it. The setup script walks you through everything:
+The setup walks you through five steps:
 
-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
+1. **Tailscale auth key** — prompts for one, or reuses the key already in zo secrets
+2. **Tailscale install** — sets up the VPN sidecar via [zotail](https://github.com/ssdavidai/zotail)
+3. **OpenClaw install** — installs the agent platform
+4. **Onboarding** — interactive wizard to pick your AI provider and model
+5. **Bootstrap** — configures the gateway for secure tailnet access and registers it as a service
 
-### After setup
+At the end, you'll see your Control UI URL and can launch the TUI immediately.
 
-On first browser load, the Control UI will request device pairing. Approve it once from the CLI:
+### First browser connection
+
+The first time you open the Control UI from another device on your tailnet, you need to approve the device once:
 
 ```bash
 openclaw devices list
 openclaw devices approve <request-id>
 ```
 
-After that, the browser is permanently paired.
+Refresh the browser and you're in. This is a one-time step per device.
 
-## Why this exists
+## Development channel
 
-After a fresh `openclaw configure` on Zo, the default gateway config doesn't work with Tailscale. You'll hit a series of issues:
+To test in-development versions:
 
-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.
+```bash
+npm install -g @ssdavidai/zoclaw@next
+zoclaw init --next
+```
 
-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.
+The `--next` flag pulls `@next` versions of dependencies. Without it, stable `@latest` versions are used.
 
-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.
+## Managing the gateway
 
-4. **Security audit failures** -- The default config ships with invalid `denyCommands` entries and overly permissive credentials directory permissions.
+The gateway runs as a supervised service — it starts automatically and restarts on failure.
 
-## What the bootstrap patches
+```bash
+# Check status
+supervisorctl -c /etc/zo/supervisord-user.conf status openclaw-gateway
 
-| 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` |
+# Restart
+supervisorctl -c /etc/zo/supervisord-user.conf restart openclaw-gateway
+
+# View logs
+tail /dev/shm/openclaw-gateway.log
+```
 
-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.
+## How it works
 
-## Scripts
+A fresh `openclaw configure` on Zo doesn't work with Tailscale out of the box. Tailscale Serve terminates TLS on the edge and proxies to your gateway as plain HTTP on loopback. The gateway sees a localhost socket but a remote-looking `Host` header (your `.ts.net` hostname), misclassifies the connection, and rejects it.
 
-| Script | Purpose |
-|---|---|
-| `zoclaw init` | Full setup from scratch (Tailscale + OpenClaw + bootstrap) |
-| `zoclaw bootstrap` | Config patches only (if OpenClaw and Tailscale are already installed) |
+zoclaw fixes this by patching the gateway config to:
 
-## Security
+- Use OpenClaw's native Tailscale Serve integration (`gateway.tailscale.mode: "serve"`)
+- Trust Tailscale identity headers for browser connections (`gateway.auth.allowTailscale`)
+- Trust localhost as a reverse proxy (`gateway.trustedProxies`) so forwarded headers are honored
+- Enable the browser Control UI
+- Set the agent workspace to `/home/workspace/` (Zo standard)
+- Migrate secrets (gateway token, API keys) to zo secrets
 
-Running `openclaw security audit` after setup should show **0 critical findings**. The setup uses `trustedProxies` + proper device pairing instead of insecure bypasses.
+The bootstrap uses a **two-phase restart** because `trustedProxies` and local device auto-pairing conflict. When `127.0.0.1` is listed as a trusted proxy, the gateway treats direct CLI connections as proxy traffic and can't auto-pair them. So the bootstrap starts the gateway *without* `trustedProxies` first (allowing the local CLI to auto-pair), then adds it and restarts.
+
+No insecure flags (`allowInsecureAuth`, `dangerouslyDisableDeviceAuth`) are used. Browser access goes through proper Ed25519 device pairing.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `zoclaw init` | Full setup from scratch |
+| `zoclaw init --next` | Full setup using development channel |
+| `zoclaw bootstrap` | Re-apply config patches only (if already installed) |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssdavidai/zoclaw",
-  "version": "1.3.0-next.6",
+  "version": "1.3.0",
   "description": "Set up OpenClaw on Zo with Tailscale access in one command",
   "license": "MIT",
   "repository": {

package/scripts/bootstrap.sh

@@ -215,13 +215,24 @@ else
   echo "  Logs:  tail /dev/shm/openclaw-gateway.log /dev/shm/openclaw-gateway_err.log"
 fi
 
-# ─── 6. Print access info ─────────────────────────────────────────────
+# ─── 6. Provision HTTPS certificate ───────────────────────────────────
 
 TS_HOSTNAME=$(tailscale status --json 2>/dev/null | node -pe "
   const s = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
   (s.Self.DNSName || '').replace(/\\.\$/g, '')
 " 2>/dev/null || true)
 
+if [ -n "$TS_HOSTNAME" ]; then
+  echo ""
+  echo "Provisioning HTTPS certificate..."
+  if tailscale cert "$TS_HOSTNAME" 2>/dev/null; then
+    echo "  Certificate ready for ${TS_HOSTNAME}"
+  else
+    echo "  Warning: certificate provisioning failed."
+    echo "  Ensure HTTPS certificates are enabled at https://login.tailscale.com/admin/dns"
+  fi
+fi
+
 echo ""
 echo "Ready!"
 echo "  TUI:     openclaw tui"