docs(cli): add CLI reference and workshop-mode guide

danielgorgonha · danielgorgonha · commit 47d2d6b63f72 · 2026-04-09T15:07:33.000-03:00
Adds two new pages documenting the recently-shipped `clawhalla` CLI and the
remote-tunnel workshop flow it enables:

- `/cli/` — full command reference for `connect`, `disconnect`, `status` and
  the `mc install/start/stop/status/logs/open` subcommands. Covers every flag
  (including `--no-bridge` for bare-OpenClaw VPSs and `--bind 0.0.0.0` with
  the security caveat) and lists what the CLI writes to `~/.clawhalla/`.
- `/guides/workshop-mode/` — end-to-end walkthrough for the ipe.city-style
  setup where the VPS is already running OpenClaw and you just want to drive
  it from your laptop. Walks through install → start → tunnel → onboard →
  squad creation → teardown, plus a table of the five connectivity-banner
  states and what to do for each.

Updates the docs landing page to present the two paths (local Docker launcher
vs remote tunnel + local MC) as equal-weight first-class options instead of
burying the CLI path, and wires both new pages into the Starlight sidebar.

Build verified locally (17 pages, was 15; pagefind index updated).
diff --git a/astro.config.mjs b/astro.config.mjs
@@ -27,10 +27,17 @@ export default defineConfig({
             { label: 'Server Setup', link: '/getting-started/server-setup/' },
           ],
         },
+        {
+          label: 'CLI',
+          items: [
+            { label: 'Overview', link: '/cli/' },
+          ],
+        },
         {
           label: 'Guides',
           items: [
             { label: 'Your First Agent', link: '/guides/first-agent/' },
+            { label: 'Workshop mode (remote tunnel)', link: '/guides/workshop-mode/' },
             { label: 'Customization', link: '/guides/customization/' },
             { label: 'Content Pipeline', link: '/guides/content-pipeline/' },
             { label: 'Autopilot', link: '/guides/autopilot/' },
diff --git a/src/content/docs/cli/index.mdx b/src/content/docs/cli/index.mdx
@@ -0,0 +1,126 @@
+---
+title: ClawHalla CLI
+description: The clawhalla CLI — SSH tunnel to a remote OpenClaw gateway and run Mission Control locally.
+---
+
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+The `clawhalla` CLI gives you two things on one command:
+
+1. **`clawhalla connect`** — opens an SSH tunnel from your laptop to a remote VPS running OpenClaw, so Mission Control can talk to a gateway you do not have to install locally.
+2. **`clawhalla mc`** — installs and runs Mission Control in the background, without touching a `cd apps/mission-control && pnpm install && pnpm dev` dance.
+
+This is the path most workshop users want. If you would rather run the whole OpenClaw stack locally in Docker, see [Installation](/getting-started/installation/).
+
+## Install
+
+The CLI currently ships from the monorepo. Clone the repo and link the `clawhalla` binary on your PATH:
+
+```bash
+git clone https://github.com/deegalabs/clawhalla.git
+cd clawhalla/apps/cli
+pnpm install && pnpm build
+ln -s "$(pwd)/bin/clawhalla.js" ~/.local/bin/clawhalla
+clawhalla --version
+```
+
+Make sure `~/.local/bin` is on your `PATH`.
+
+## Command reference
+
+### `clawhalla connect <target>`
+
+Opens an SSH tunnel to a remote OpenClaw gateway and publishes it on a local port so Mission Control can talk to it.
+
+```bash
+clawhalla connect root@vps.example.com:22022 \
+  --alias my-box \
+  --remote-gateway-port 47716 \
+  --no-bridge
+```
+
+| Flag | Purpose |
+| --- | --- |
+| `--alias <name>` | Local alias for the tunnel. Defaults to the first DNS label of the host. |
+| `--identity <path>` | SSH private key to use. Defaults to the ClawHalla-managed key in `~/.clawhalla/keys/id_ed25519`, auto-generated on first run. |
+| `--remote-gateway-port <port>` | Remote OpenClaw HTTP gateway port. Default `18789`. Workshop VPSs often publish it on a different port (e.g. `47716`). |
+| `--remote-bridge-port <port>` | Remote OpenClaw WS bridge port. Default `18790`. |
+| `--no-bridge` | Skip the WS bridge forward entirely. Use this for bare-OpenClaw VPSs that only publish the HTTP gateway port. |
+| `--bind <host>` | Local interface to bind the forwarded ports on. Default `127.0.0.1`. Use `0.0.0.0` if Mission Control runs inside a Docker container on Linux. |
+| `--skip-probe` | Skip the BatchMode SSH probe. Useful for password-only targets. |
+| `--no-auto-key` | Do not auto-generate or install a ClawHalla-managed SSH key. |
+
+### `clawhalla disconnect [alias]`
+
+Closes an active tunnel. Pass an alias, or `--all` to close every tunnel at once.
+
+```bash
+clawhalla disconnect my-box
+clawhalla disconnect --all
+```
+
+### `clawhalla status`
+
+Lists every active tunnel with its local ports and the remote target.
+
+```bash
+clawhalla status
+```
+
+### `clawhalla mc <subcommand>`
+
+Installs and runs Mission Control without leaving the CLI.
+
+| Subcommand | What it does |
+| --- | --- |
+| `mc install` | Checks `git`/`pnpm`, clones the clawhalla repo into `~/.clawhalla/source` (or reuses the current checkout if you're inside the monorepo), runs `pnpm install`, creates `~/.openclaw/workspace` and `apps/mission-control/data`. |
+| `mc start [--port 3000]` | Spawns `pnpm dev` detached so it survives the CLI exit. Writes the pid to `~/.clawhalla/mc.pid` and polls the HTTP root until it responds. Prints the URL + PID + log path. |
+| `mc stop` | Sends `SIGTERM` to the Mission Control process group, falls back to `SIGKILL` after a grace period, clears the pidfile. |
+| `mc status [--port 3000]` | Reports whether the pid is alive and whether HTTP is responding. |
+| `mc logs [-f]` | Dumps the last 16 KB of the log. With `-f`, shells out to `tail -f` (Linux/macOS). On Windows, prints a `Get-Content -Wait` hint. |
+| `mc open [--port 3000]` | Opens Mission Control in your default browser (cross-platform: `xdg-open` / `open` / `start`). |
+
+## Typical flow
+
+```bash
+# 1. Install MC once
+clawhalla mc install
+
+# 2. Start it in the background
+clawhalla mc start
+
+# 3. Open an SSH tunnel to a remote OpenClaw gateway
+clawhalla connect root@vps.example.com:22022 --remote-gateway-port 47716 --no-bridge
+
+# 4. Open the browser
+clawhalla mc open
+```
+
+When you finish:
+
+```bash
+clawhalla disconnect --all
+clawhalla mc stop
+```
+
+## State on disk
+
+Everything the CLI writes lives under `~/.clawhalla/`:
+
+- `tunnels.json` — registry of active tunnels (read by Mission Control's connectivity banner)
+- `keys/id_ed25519` — managed SSH key used for `clawhalla connect`
+- `source/` — managed clone of the clawhalla monorepo (only if you did not run from a checkout)
+- `mc.pid`, `mc.log` — Mission Control process state and output
+
+Nothing writes outside that directory. Deleting `~/.clawhalla/` fully resets the CLI.
+
+## Next steps
+
+<CardGrid>
+  <Card title="Workshop mode" icon="rocket">
+    [End-to-end walkthrough](/guides/workshop-mode/) against a remote VPS.
+  </Card>
+  <Card title="Configuration" icon="setting">
+    [Environment variables](/reference/environment/) and `openclaw.json`.
+  </Card>
+</CardGrid>
diff --git a/src/content/docs/guides/workshop-mode.mdx b/src/content/docs/guides/workshop-mode.mdx
@@ -0,0 +1,100 @@
+---
+title: Workshop mode (remote tunnel)
+description: Run Mission Control on your laptop against a remote OpenClaw gateway over an SSH tunnel.
+---
+
+Workshop mode is for the case where OpenClaw is already running on a remote VPS (typical of ipe.city-style buildathon boxes) and you only want to drive it from your laptop. No local Docker, no local OpenClaw install — just an SSH tunnel and Mission Control.
+
+## Prerequisites
+
+- `git`, `pnpm`, and `node` 20+ on your machine
+- SSH access to a VPS that is running OpenClaw and publishing the HTTP gateway on some port (default `18789`, but workshop boxes often use a mapped port like `47716`)
+- The `clawhalla` CLI on your `PATH` (see [ClawHalla CLI — Install](/cli/))
+
+## Step 1 — Install Mission Control locally
+
+```bash
+clawhalla mc install
+```
+
+This clones the clawhalla repo into `~/.clawhalla/source` (or reuses the current checkout if you are already inside the monorepo), runs `pnpm install`, and creates the Mission Control data directory. Run this once per machine.
+
+## Step 2 — Start Mission Control
+
+```bash
+clawhalla mc start
+```
+
+Mission Control is spawned detached, so the dev server keeps running after the CLI exits. The command prints the URL, the pid, and the log file path, then returns. If you tail the log:
+
+```bash
+clawhalla mc logs -f
+```
+
+## Step 3 — Open an SSH tunnel to the remote gateway
+
+```bash
+clawhalla connect root@vps.example.com:22022 \
+  --alias workshop \
+  --remote-gateway-port 47716 \
+  --no-bridge
+```
+
+Breakdown of the flags:
+
+- `root@vps.example.com:22022` — the VPS SSH target (user, host, optional port)
+- `--alias workshop` — a friendly name for this tunnel, used by `disconnect` / `status`
+- `--remote-gateway-port 47716` — the port OpenClaw is published on inside the VPS. If you omit this, the CLI assumes `18789` (the OpenClaw default)
+- `--no-bridge` — skip the secondary WS bridge forward. Bare-OpenClaw VPSs only publish the HTTP gateway, not the bridge; the flag makes the CLI tolerate that
+
+The first time you run this, the CLI will generate an `ed25519` keypair under `~/.clawhalla/keys/` and try to install the public half on the VPS via `ssh-copy-id`. On subsequent runs it reuses the same key and connects without prompting.
+
+:::caution[`--bind 0.0.0.0`]
+If you run Mission Control inside a Docker container on Linux and it is trying to reach the tunnel from outside the host network namespace, pass `--bind 0.0.0.0`. The CLI prints a security warning when you do this — the tunnel becomes reachable from anywhere on your LAN, so only use it on trusted networks.
+:::
+
+## Step 4 — Open Mission Control
+
+```bash
+clawhalla mc open
+```
+
+At the top of the onboarding wizard you should see a green banner:
+
+> ● Connected via ClawHalla tunnel
+> workshop → vps.example.com · local :18789 → remote :47716
+
+If the banner is red or amber, the [Connectivity states](#connectivity-states) section below tells you what to do.
+
+## Step 5 — Drive onboarding
+
+Fill in the wizard. The gateway URL should already be `http://127.0.0.1:18789` (or whatever local port the CLI allocated — Mission Control detects this automatically). You will need to provide:
+
+- The gateway token (you can fetch it from the VPS: `docker exec <container> cat /home/node/.openclaw/openclaw.json` and look for `gateway.auth.token`)
+- An Anthropic or Google API key (or pick Ollama / skip)
+- The squad you want to create — `hackathon` ships with six agents (Thor, Odin, Freya, Tyr, Heimdall, Bragi) and nine skills per agent out of the box
+
+After you finish onboarding, Mission Control generates IDENTITY.md / SOUL.md / skills under `~/.openclaw/workspace/squads/<squad>/<agent>/` for every agent on the team.
+
+## Step 6 — Tear down
+
+```bash
+clawhalla disconnect --all
+clawhalla mc stop
+```
+
+Both are idempotent — running them when there is nothing to tear down is a no-op.
+
+## Connectivity states
+
+Mission Control polls `/api/connection/probe` every four seconds and renders one of these banners:
+
+| Banner | What it means | Fix |
+| --- | --- | --- |
+| **● Connected via ClawHalla tunnel** (green) | Tunnel is up and the remote gateway is answering HTTP | Nothing. Proceed with onboarding. |
+| **▲ Tunnel up, remote gateway not responding** (amber) | SSH tunnel is alive but OpenClaw on the VPS is not answering | Check OpenClaw is running on the VPS: `ssh <vps> "docker ps"` |
+| **■ ClawHalla tunnel has exited** (red) | `~/.clawhalla/tunnels.json` has entries but the SSH pid is gone — usually after a reboot | `clawhalla connect ...` again |
+| **▲ Local OpenClaw config detected** (amber) | No tunnel, but `~/.openclaw/openclaw.json` exists from a local install | Start local OpenClaw, or run `clawhalla connect` |
+| **■ No OpenClaw connection detected** (red) | Nothing found anywhere | `clawhalla connect <vps>` or install OpenClaw locally |
+
+The banner auto-refreshes, so you can bring a tunnel up in a second terminal and watch the state flip to green without reloading the page.
diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx
@@ -5,32 +5,48 @@ description: Your AI agent's hall of glory. Running in one command.
 
 import { Card, CardGrid } from '@astrojs/starlight/components';
 
-ClawHalla is an opinionated distribution of [OpenClaw](https://openclaw.ai) that removes all setup friction. One command gets you a running AI agent system with Mission Control, pre-trained agents, and a management dashboard.
+ClawHalla is the fastest way to run [OpenClaw](https://openclaw.ai). Two paths, same destination.
 
-## Why ClawHalla?
+## Pick your path
 
-OpenClaw is a powerful AI agent framework, but setting it up requires navigating auth profiles, model configuration, and multiple CLI commands. ClawHalla wraps all of this in a guided installer with a web dashboard.
+<CardGrid>
+  <Card title="Local Docker launcher" icon="rocket">
+    Run the whole OpenClaw stack on your machine in Docker. Best when you want a self-contained environment and you're happy to pull the full image locally.
 
-**One command. Everything configured. Agents ready.**
+    ```bash
+    curl -fsSL https://clawhalla.xyz/install.sh | bash
+    ```
 
-## Quick Start
+    [Full installation →](/getting-started/installation/)
+  </Card>
+  <Card title="Remote tunnel + local MC" icon="seti:config">
+    Keep the OpenClaw gateway on a remote VPS and run Mission Control on your laptop over an SSH tunnel. Best for workshops and buildathons where someone else already set up the VPS.
 
-```bash
-curl -fsSL https://clawhalla.xyz/install.sh | bash
-```
+    ```bash
+    clawhalla mc install && clawhalla mc start
+    clawhalla connect root@vps.example.com:22022 --no-bridge
+    ```
 
-The installer will ask for:
-- A workspace name
-- Install mode (Docker or bare metal)
-- Which services to include (Mission Control, Ollama)
+    [Workshop mode guide →](/guides/workshop-mode/)
+  </Card>
+</CardGrid>
 
-Then open Mission Control at `http://localhost:3000` to connect your AI provider and start using agents.
+## Why ClawHalla?
+
+OpenClaw is a powerful AI agent framework, but setting it up by hand requires Node, pnpm, multiple CLI commands, and understanding the ecosystem. ClawHalla gives you:
+
+- A pre-configured Docker container for the all-in-one local path
+- A `clawhalla` CLI with `connect` (SSH tunnels) and `mc` (install/start/stop Mission Control) for the remote path
+- Mission Control — a browser UI for onboarding, squads, agents, and skills
 
 ## Next Steps
 
 <CardGrid>
   <Card title="Installation" icon="rocket">
-    [Full installation guide with Docker and bare metal options](/getting-started/installation/)
+    [Detailed installation guide](/getting-started/installation/) for the local Docker path
+  </Card>
+  <Card title="ClawHalla CLI" icon="seti:powershell">
+    [Command reference](/cli/) for `connect`, `disconnect`, `status`, and `mc`
   </Card>
   <Card title="Configuration" icon="setting">
     [Configure providers, models, and channels](/getting-started/configuration/)
