openclaw-spawn 1.0.0

package/Dockerfile

@@ -0,0 +1,45 @@
+FROM node:22-bookworm
+
+# Install system dependencies for browser automation and VNC remote access
+RUN apt-get update && apt-get install -y \
+    curl \
+    wget \
+    ca-certificates \
+    xvfb \
+    x11vnc \
+    novnc \
+    websockify \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install OpenClaw from npm
+RUN npm install -g openclaw@latest
+
+# Install Playwright and Chromium with full system dependencies as root
+RUN npx playwright install chromium --with-deps
+
+# Create node user directories first
+RUN mkdir -p /home/node/.cache/ms-playwright /home/node/.openclaw /workspace
+
+# Copy browsers to node user location
+RUN cp -r /root/.cache/ms-playwright/* /home/node/.cache/ms-playwright/ 2>/dev/null || true
+
+# Set proper ownership before switching to node user
+RUN chown -R node:node /home/node/.cache /home/node/.openclaw /workspace
+
+# Create stable symlink for OpenClaw browser.executablePath
+RUN CHROMIUM_DIR=$(ls -d /home/node/.cache/ms-playwright/chromium-* 2>/dev/null | head -1) && \
+    if [ -n "$CHROMIUM_DIR" ]; then \
+        ln -sf "$CHROMIUM_DIR/chrome-linux/chrome" /home/node/openclaw-chromium && \
+        chown -h node:node /home/node/openclaw-chromium; \
+    fi
+
+# Verify Chromium is accessible and executable
+RUN su - node -c "test -x /home/node/openclaw-chromium || echo 'Warning: Chromium not found or not executable'"
+
+USER node
+ENV PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright
+ENV HOME=/home/node
+ENV DISPLAY=:99
+
+WORKDIR /workspace
+CMD ["sh", "-c", "Xvfb :99 -screen 0 1280x900x24 -ac +extension GLX +render -noreset & tail -f /dev/null"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ostap Hembara
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/QUICKSTART.md

@@ -0,0 +1,46 @@
+# QuickStart
+
+## First time setup
+
+```bash
+git clone https://github.com/ostapagon/openclaw-spawn.git
+cd openclaw-spawn
+npm install -g .
+openclaw-spawn init
+```
+
+`init` handles everything automatically:
+- Installs Docker if missing (macOS: brew, Linux: apt/yum, Windows: prints download link)
+- Builds the base Docker image
+- Runs the OpenClaw onboarding wizard (API key, model selection)
+- Starts the gateway with browser support ready
+
+## After init
+
+```bash
+openclaw-spawn tui        # chat with your agent (browser works out of the box)
+openclaw-spawn browser    # open VNC tab to see/control the browser visually
+openclaw-spawn dashboard  # open the web control panel
+```
+
+## Multiple instances
+
+```bash
+openclaw-spawn onboard    # add another instance
+openclaw-spawn list       # see all instances
+```
+
+## Manual steps (if you prefer)
+
+```bash
+openclaw-spawn build      # build Docker image
+openclaw-spawn onboard    # create instance + run OpenClaw onboarding
+openclaw-spawn gateway -d # start gateway in background (bootstraps Chrome too)
+openclaw-spawn tui        # start chatting
+```
+
+## Ports (per instance)
+
+- **+0**: Gateway / dashboard
+- **+11**: Chrome CDP
+- **+20**: noVNC browser view

package/README.md

@@ -0,0 +1,237 @@
+# OpenClaw Swarm
+
+Docker orchestrator for running multiple [OpenClaw](https://openclaw.ai) instances with browser automation support.
+
+## Installation
+
+```bash
+npm install -g openclaw-spawn
+```
+
+Or link locally for development:
+```bash
+git clone https://github.com/yourusername/openclaw-spawn.git
+cd openclaw-spawn
+npm install
+npm link
+```
+
+f451c93c-534a-4c84-8822-     │ d8b295 │ operat │ 140.82.    │ just   │        │
+│ c039b6c52bd1 
+
+## Quick Start
+
+1. **Build the Docker base image** (first time only):
+```bash
+openclaw-spawn build
+```
+
+2. **Run any OpenClaw command** - it will prompt you to select or create an instance:
+```bash
+openclaw-spawn onboard
+```
+
+3. **Select "Add new instance"** and name it (e.g., `worker1`)
+
+4. **Configure OpenClaw** using the native wizard that appears
+
+5. **Start the gateway**:
+```bash
+openclaw-spawn gateway
+```
+
+6. **Access the dashboard** at `http://localhost:18789`
+
+## Usage
+
+### OpenClaw Commands
+
+Any OpenClaw command automatically shows an instance selector:
+
+```bash
+openclaw-spawn onboard              # Run onboarding wizard
+openclaw-spawn gateway              # Start gateway
+openclaw-spawn tui                  # Open TUI
+openclaw-spawn channels status      # Check channels
+openclaw-spawn devices list         # List devices
+openclaw-spawn devices approve <ID> # Approve a device (pairing)
+openclaw-spawn dashboard            # Open dashboard
+```
+
+**Device pairing (first-time dashboard):** When you open the dashboard URL you'll see "pairing required". Run `openclaw-spawn devices list`, copy the REQUEST_ID, then `openclaw-spawn devices approve <REQUEST_ID>`. Refresh the browser.
+
+### Management Commands
+
+```bash
+openclaw-spawn list                 # List all instances
+openclaw-spawn remove worker1       # Remove an instance
+openclaw-spawn stop worker1         # Stop an instance
+openclaw-spawn start worker1        # Start an instance
+openclaw-spawn logs worker1 -f      # Follow logs
+openclaw-spawn build                # Build Docker image
+openclaw-spawn cleanup              # Remove all containers and reset
+```
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────┐
+│  openclaw-spawn (npm CLI)                           │
+│  - Manages instance metadata                        │
+│  - Shows interactive selector                       │
+│  - Routes commands to containers                    │
+└────────────────┬────────────────────────────────────┘
+                 │
+    ┌────────────┴──────────────┐
+    │                           │
+┌───▼────────┐          ┌───────▼───────┐
+│ worker1    │          │ worker2       │
+│ Container  │          │ Container     │
+│            │          │               │
+│ OpenClaw   │          │ OpenClaw      │
+│ + Chromium │          │ + Chromium    │
+│            │          │               │
+│ Port 18789 │          │ Port 19001    │
+└────────────┘          └───────────────┘
+```
+
+- Each instance runs in its own Docker container
+- Containers have OpenClaw installed from npm
+- Chromium included for browser automation
+- Isolated configuration and workspace per instance
+- Data stored in `~/.openclaw-spawn/instances/`
+
+**Port mapping:** Internal port matches external: each instance is assigned a host port (oc-1 → 18789, oc-2 → 19009, …). We map `host_port:host_port` and set OpenClaw’s `gateway.port` to that port so the URL OpenClaw prints is correct. `openclaw-spawn dashboard` also prints the correct URL with token after the command.
+
+**Starting fresh:** To remove all containers and metadata, run `openclaw-spawn cleanup` or `./cleanup.sh`.
+
+
+## Features
+
+- **Simple UX** - Just run commands, select or create instances
+- **Native OpenClaw** - Uses official OpenClaw wizards and tools
+- **Browser support** - Chromium included for automation
+- **Multi-instance** - Run many OpenClaw instances in parallel
+- **Isolated** - Each instance has separate config and workspace
+- **No Docker knowledge needed** - CLI abstracts all Docker commands
+
+## Example Workflow
+
+```bash
+# Create and configure first instance
+$ openclaw-spawn onboard
+? Select instance: ➕ Add new instance
+? Enter instance name: email-bot
+# ... OpenClaw wizard runs ...
+
+# Start gateway on that instance
+$ openclaw-spawn gateway
+? Select instance: 🟢 email-bot (port 18789, running)
+✓ Starting gateway...
+
+# Create another instance
+$ openclaw-spawn onboard
+? Select instance: ➕ Add new instance
+? Enter instance name: scraper
+
+# List all instances
+$ openclaw-spawn list
+📋 OpenClaw Instances:
+
+🟢 email-bot
+  Port: 18789
+  Status: running
+  Container: openclaw-email-bot
+  
+🟢 scraper
+  Port: 19001
+  Status: running
+  Container: openclaw-scraper
+```
+
+## Data Storage
+
+- **Metadata:** `~/.openclaw-spawn/instances.json`
+- **Instance data:** `~/.openclaw-spawn/instances/<name>/`
+  - `.openclaw/` - OpenClaw configuration
+  - `workspace/` - Instance workspace files
+
+## Requirements
+
+- Docker Desktop
+- Node.js 18+
+- macOS, Linux, or Windows with WSL2
+
+## Troubleshooting
+
+### "Pairing required" when opening the dashboard
+OpenClaw requires device pairing for security. When you first open the dashboard, you'll see "disconnected (1008): pairing required".
+
+**Steps to approve your browser:**
+
+1. **List pending devices:**
+   ```bash
+   openclaw-spawn devices list
+   ```
+   You'll see output like:
+   ```
+   REQUEST_ID | STATUS  | AGENT | DEVICE NAME
+   abc123     | Pending | main  | Chrome on Mac
+   ```
+
+2. **Approve the device:**
+   ```bash
+   openclaw-spawn devices approve abc123
+   ```
+   (Use the REQUEST_ID from the first column)
+
+3. **Refresh the dashboard** - it should now connect successfully!
+
+**Note:** You only need to do this once per browser/device. The approval persists.
+
+### Docker not running
+```
+✗ Docker is not running. Please start Docker Desktop.
+```
+→ Start Docker Desktop and try again
+
+### Build fails
+```bash
+# Clean and rebuild
+docker rmi openclaw-spawn-base:latest
+openclaw-spawn build
+```
+
+### Instance won't start
+```bash
+# Check logs
+openclaw-spawn logs instance-name
+
+# Remove and recreate
+openclaw-spawn remove instance-name
+openclaw-spawn onboard  # Create new one
+```
+
+## Development
+
+```bash
+# Clone and setup
+git clone https://github.com/yourusername/openclaw-spawn.git
+cd openclaw-spawn
+npm install
+npm link
+
+# Make changes to src/
+# Test with: openclaw-spawn <command>
+
+# Unlink when done
+npm unlink -g openclaw-spawn
+```
+
+## License
+
+MIT
+
+## Credits
+
+Built for [OpenClaw](https://openclaw.ai) by the community.

package/bin/openclaw-spawn.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { cli } from '../src/cli.js';
+
+cli(process.argv.slice(2));

package/cleanup.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+# Cleanup script - removes all openclaw-spawn containers and metadata
+# Run this to start fresh
+
+echo "🧹 Cleaning up OpenClaw Swarm..."
+
+# Stop and remove all openclaw-* containers
+echo "Stopping containers..."
+docker ps -a --filter "name=openclaw-" --format "{{.Names}}" | xargs -r docker stop 2>/dev/null
+echo "Removing containers..."
+docker ps -a --filter "name=openclaw-" --format "{{.Names}}" | xargs -r docker rm 2>/dev/null
+
+# Clear all instance config (keeps directory structure)
+echo "Clearing instance configs..."
+if [ -d ~/.openclaw-spawn/instances ]; then
+  find ~/.openclaw-spawn/instances -mindepth 2 -type f -delete 2>/dev/null
+  find ~/.openclaw-spawn/instances -mindepth 2 -type d -empty -delete 2>/dev/null
+fi
+
+# Remove metadata
+echo "Clearing metadata..."
+rm -f ~/.openclaw-spawn/instances.json
+echo '{"instances":{},"nextPort":18789}' > ~/.openclaw-spawn/instances.json
+
+# Uncomment to delete all instance directories entirely
+# echo "Removing instance data..."
+# rm -rf ~/.openclaw-spawn/instances/*
+
+echo "✅ Cleanup complete! Re-add instances with: openclaw-spawn onboard"

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "openclaw-spawn",
+  "version": "1.0.0",
+  "description": "Docker orchestrator for multiple OpenClaw instances",
+  "type": "module",
+  "bin": {
+    "openclaw-spawn": "./bin/openclaw-spawn.js"
+  },
+  "scripts": {
+    "test": "node test/test.js"
+  },
+  "keywords": ["openclaw", "docker", "orchestrator", "ai", "agent"],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "inquirer": "^9.2.0",
+    "commander": "^11.1.0",
+    "chalk": "^5.3.0"
+  }
+}