@linkclaw/clawpool 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 CLI tool to manage OpenClaw container instances on a local Docker host (Mac Mini + Colima).
 
-Each instance runs in its own Docker container with a dedicated Telegram bot token, persistent volume, and auto-assigned port.
+Each instance gets its own Web Dashboard with an auto-generated auth token — no Telegram or external accounts required.
 
 ## Prerequisites
 
@@ -19,8 +19,8 @@ brew services start colima
 ## Install
 
 ```bash
-# Via npx (no install needed)
-npx @linkclaw/clawpool list
+# Via bunx (no install needed)
+bunx @linkclaw/clawpool list
 
 # Or install globally
 npm i -g @linkclaw/clawpool
@@ -30,14 +30,14 @@ clawpool list
 ## Usage
 
 ```
-clawpool create <name> -t <telegram_bot_token> [-p <port>] [-e KEY=VAL ...]
+clawpool create <name> [--telegram-token <token>] [-p <port>] [-e KEY=VAL ...]
 clawpool list [--json]
 clawpool start <name>
 clawpool stop <name>
 clawpool restart <name>
 clawpool delete <name> [--purge]
 clawpool rename <old_name> <new_name>
-clawpool config <name> [-t <new_token>] [-e KEY=VAL ...]
+clawpool config <name> [--telegram-token <token>] [-e KEY=VAL ...]
 clawpool logs <name> [-f]
 clawpool status <name>
 clawpool shell <name>
@@ -47,35 +47,33 @@ clawpool image [set <image> | show]
 ## Quick Start
 
 ```bash
-# 1. Build or pull the OpenClaw image
-docker build -t openclaw:latest /path/to/apps/agent
+# 1. Create an instance — dashboard URL is printed automatically
+clawpool create alpha
 
-# 2. Create an instance with a Telegram bot token
-clawpool create alpha -t "123456:AAHxxx..."
+# 2. Add another with extra env vars
+clawpool create beta -e "OPENAI_API_KEY=sk-..."
 
-# 3. Add another instance with extra env vars
-clawpool create beta -t "789012:BBXyyy..." -e "OPENAI_API_KEY=sk-..."
+# 3. Optionally attach Telegram
+clawpool create gamma --telegram-token "123456:AAH..."
 
-# 4. Check running instances
+# 4. List all instances with dashboard URLs
 clawpool list
 
 # 5. View logs
 clawpool logs alpha -f
 
-# 6. Reconfigure
-clawpool config alpha -t "new_token_here"
-
-# 7. Clean up
+# 6. Clean up
 clawpool delete beta --purge
 ```
 
 ## How It Works
 
-- **Config**: `~/.clawpool/config.json` stores instance metadata (name, port, token, env vars).
+- **Dashboard**: Each instance exposes OpenClaw's built-in Web UI. Auth token is auto-generated and shown in `clawpool list`.
+- **Config**: `~/.clawpool/config.json` stores instance metadata.
 - **Containers**: Each instance runs as `claw-<name>` with `--restart unless-stopped`.
 - **Volumes**: Data persisted in Docker named volumes (`claw-<name>-data` mounted at `/home/claw`).
-- **Ports**: Auto-assigned starting from 8081, or manually specified with `-p`.
-- **Telegram**: Each instance connects via long-polling (no public IP needed).
+- **Ports**: Auto-assigned starting from 18789 with 20-port spacing (OpenClaw requirement), or manually specified with `-p`.
+- **Telegram**: Optional — pass `--telegram-token` to enable Telegram bot integration via long-polling.
 
 ## Config File
 
@@ -83,13 +81,13 @@ Stored at `~/.clawpool/config.json`:
 
 ```jsonc
 {
-  "image": "openclaw:latest",   // default image for new instances
-  "next_port": 8083,            // next auto-assigned port
+  "image": "openclaw:latest",
+  "next_port": 18829,
   "instances": {
     "alpha": {
       "name": "alpha",
-      "port": 8081,
-      "telegram_bot_token": "123456:AAH...",
+      "port": 18789,
+      "gateway_token": "abc123...",
       "status": "running",
       "container_id": "a1b2c3...",
       "volume": "claw-alpha-data",

package/clawpool.ts

@@ -1,19 +1,23 @@
 #!/usr/bin/env bun
 
 import { existsSync, mkdirSync } from "fs";
-import { homedir } from "os";
+import { homedir, networkInterfaces } from "os";
 import { join } from "path";
+import { randomBytes } from "crypto";
 
 // ── Config ──────────────────────────────────────────────────────────────────
 
 const CLAWPOOL_DIR = process.env.CLAWPOOL_DIR ?? join(homedir(), ".clawpool");
 const CONFIG_FILE = join(CLAWPOOL_DIR, "config.json");
 const CONTAINER_PREFIX = "claw";
+const BASE_PORT = 18789;
+const PORT_STEP = 20; // OpenClaw requires at least 20-port spacing
 
 interface Instance {
   name: string;
   port: number;
-  telegram_bot_token: string;
+  gateway_token: string;
+  telegram_bot_token?: string;
   status: "running" | "stopped" | "removed";
   container_id: string;
   volume: string;
@@ -35,6 +39,7 @@ const c = {
   yellow: (s: string) => `\x1b[33m${s}\x1b[0m`,
   cyan: (s: string) => `\x1b[36m${s}\x1b[0m`,
   bold: (s: string) => `\x1b[1m${s}\x1b[0m`,
+  dim: (s: string) => `\x1b[2m${s}\x1b[0m`,
 };
 
 const die = (msg: string): never => {
@@ -46,6 +51,21 @@ const ok = (msg: string) => console.log(`${c.green("✓")} ${msg}`);
 
 const containerName = (name: string) => `${CONTAINER_PREFIX}-${name}`;
 const volumeName = (name: string) => `${CONTAINER_PREFIX}-${name}-data`;
+const generateToken = () => randomBytes(24).toString("base64url");
+
+function getLanIP(): string {
+  const nets = networkInterfaces();
+  for (const addrs of Object.values(nets)) {
+    for (const addr of addrs ?? []) {
+      if (addr.family === "IPv4" && !addr.internal) return addr.address;
+    }
+  }
+  return "localhost";
+}
+
+function dashboardURL(host: string, port: number, token: string): string {
+  return `http://${host}:${port}?token=${token}`;
+}
 
 function humanTime(iso: string): string {
   const diff = Math.floor((Date.now() - new Date(iso).getTime()) / 1000);
@@ -62,7 +82,7 @@ async function loadConfig(): Promise<Config> {
   if (!existsSync(CONFIG_FILE)) {
     const initial: Config = {
       image: "openclaw:latest",
-      next_port: 8081,
+      next_port: BASE_PORT,
       instances: {},
     };
     await Bun.write(CONFIG_FILE, JSON.stringify(initial, null, 2));
@@ -91,7 +111,8 @@ async function docker(...args: string[]): Promise<string> {
   const stdout = await new Response(proc.stdout).text();
   const stderr = await new Response(proc.stderr).text();
   const code = await proc.exited;
-  if (code !== 0) throw new Error(stderr.trim() || `docker ${args[0]} failed`);
+  if (code !== 0)
+    throw new Error(stderr.trim() || `docker ${args[0]} failed`);
   return stdout.trim();
 }
 
@@ -123,26 +144,67 @@ async function syncStatus(
       "{{.State.Status}}",
       containerName(name)
     );
-    const status =
-      state === "running" ? "running" : (("stopped" as const) satisfies string);
-    config.instances[name].status = status as "running" | "stopped";
-    return status as "running" | "stopped";
+    const status: "running" | "stopped" =
+      state === "running" ? "running" : "stopped";
+    config.instances[name].status = status;
+    return status;
   } catch {
     config.instances[name].status = "removed";
     return "removed";
   }
 }
 
-function buildEnvArgs(inst: Instance): string[] {
+function openclawConfig(token: string): string {
+  return JSON.stringify({
+    gateway: {
+      auth: { mode: "token", token },
+      controlUi: { dangerouslyAllowHostHeaderOriginFallback: true },
+    },
+  });
+}
+
+function buildRunArgs(config: Config, inst: Instance): string[] {
+  const ocConfig = openclawConfig(inst.gateway_token);
+  // Init as root to fix volume permissions, write config, then drop to node user
+  const entrypoint = [
+    "sh",
+    "-c",
+    [
+      "mkdir -p /home/node/data/.openclaw",
+      "chown -R node:node /home/node/data",
+      `echo '${ocConfig}' > /home/node/data/.openclaw/openclaw.json`,
+      `exec su -s /bin/sh node -c 'exec node dist/index.js gateway --allow-unconfigured --port ${inst.port} --bind lan'`,
+    ].join(" && "),
+  ];
+
   const args = [
+    "run",
+    "-d",
+    "--name",
+    containerName(inst.name),
+    "--restart",
+    "unless-stopped",
+    "--user",
+    "root",
+    "-p",
+    `${inst.port}:${inst.port}`,
+    "-v",
+    `${inst.volume}:/home/node/data`,
     "-e",
-    `TELEGRAM_BOT_TOKEN=${inst.telegram_bot_token}`,
+    `OPENCLAW_HOME=/home/node/data`,
     "-e",
     `INSTANCE_NAME=${inst.name}`,
   ];
+
+  if (inst.telegram_bot_token) {
+    args.push("-e", `TELEGRAM_BOT_TOKEN=${inst.telegram_bot_token}`);
+  }
+
   for (const [k, v] of Object.entries(inst.env)) {
     args.push("-e", `${k}=${v}`);
   }
+
+  args.push(config.image, ...entrypoint);
   return args;
 }
 
@@ -150,28 +212,9 @@ async function rebuildContainer(
   config: Config,
   name: string
 ): Promise<string> {
-  const inst = config.instances[name];
   await dockerQuiet("rm", "-f", containerName(name));
-
-  const cid = await docker(
-    "run",
-    "-d",
-    "--name",
-    containerName(name),
-    "--restart",
-    "unless-stopped",
-    "-p",
-    `${inst.port}:8080`,
-    "-v",
-    `${inst.volume}:/home/claw`,
-    ...buildEnvArgs(inst),
-    config.image,
-    "node",
-    "dist/index.js",
-    "gateway",
-    "--allow-unconfigured"
-  );
-
+  const inst = config.instances[name];
+  const cid = await docker(...buildRunArgs(config, inst));
   inst.container_id = cid;
   inst.status = "running";
   return cid;
@@ -181,20 +224,19 @@ async function rebuildContainer(
 
 async function cmdCreate(config: Config, args: string[]) {
   let name = "";
-  let token = "";
   let port = 0;
+  let telegramToken = "";
   const env: Record<string, string> = {};
 
   for (let i = 0; i < args.length; i++) {
     switch (args[i]) {
-      case "-t":
-      case "--token":
-        token = args[++i];
-        break;
       case "-p":
       case "--port":
         port = parseInt(args[++i]);
         break;
+      case "--telegram-token":
+        telegramToken = args[++i];
+        break;
       case "-e":
       case "--env": {
         const kv = args[++i];
@@ -210,12 +252,13 @@ async function cmdCreate(config: Config, args: string[]) {
     }
   }
 
-  if (!name || !token) die("usage: clawpool create <name> -t <token>");
+  if (!name) die("usage: clawpool create <name> [--telegram-token <token>] [-p <port>] [-e KEY=VAL ...]");
   if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name))
     die("invalid name: use alphanumerics, dots, hyphens, underscores");
   if (config.instances[name]) die(`instance '${name}' already exists`);
 
   if (!port) port = config.next_port;
+  const gatewayToken = generateToken();
 
   info(`Creating instance '${name}' on port ${port}...`);
 
@@ -224,7 +267,7 @@ async function cmdCreate(config: Config, args: string[]) {
   const inst: Instance = {
     name,
     port,
-    telegram_bot_token: token,
+    gateway_token: gatewayToken,
     status: "running",
     container_id: "",
     volume: volumeName(name),
@@ -232,13 +275,17 @@ async function cmdCreate(config: Config, args: string[]) {
     created_at: new Date().toISOString(),
   };
 
+  if (telegramToken) inst.telegram_bot_token = telegramToken;
+
   config.instances[name] = inst;
-  if (config.next_port <= port) config.next_port = port + 1;
+  if (config.next_port <= port) config.next_port = port + PORT_STEP;
 
   const cid = await rebuildContainer(config, name);
   await saveConfig(config);
 
+  const host = getLanIP();
   ok(`Instance '${name}' created (port: ${port}, container: ${cid.slice(0, 12)})`);
+  console.log(`  ${c.bold("Dashboard:")} ${dashboardURL(host, port, gatewayToken)}`);
 }
 
 async function cmdList(config: Config, args: string[]) {
@@ -247,7 +294,7 @@ async function cmdList(config: Config, args: string[]) {
 
   if (names.length === 0) {
     console.log(
-      "No instances. Create one with: clawpool create <name> -t <token>"
+      "No instances. Create one with: clawpool create <name>"
     );
     return;
   }
@@ -260,7 +307,15 @@ async function cmdList(config: Config, args: string[]) {
     return;
   }
 
-  const rows = names.map((name) => {
+  const host = getLanIP();
+
+  console.log(
+    `${"NAME".padEnd(16)} ${"STATUS".padEnd(10)} ${"PORT".padEnd(7)} DASHBOARD`
+  );
+  console.log(
+    `${"----".padEnd(16)} ${"------".padEnd(10)} ${"----".padEnd(7)} ---------`
+  );
+  for (const name of names) {
     const inst = config.instances[name];
     const statusCol =
       inst.status === "running"
@@ -268,19 +323,12 @@ async function cmdList(config: Config, args: string[]) {
         : inst.status === "stopped"
           ? c.red(inst.status)
           : c.yellow(inst.status);
-    return { name, status: statusCol, port: inst.port, created: humanTime(inst.created_at) };
-  });
-
-  console.log(
-    `${"NAME".padEnd(16)} ${"STATUS".padEnd(10)} ${"PORT".padEnd(6)} CREATED`
-  );
-  console.log(
-    `${"----".padEnd(16)} ${"------".padEnd(10)} ${"----".padEnd(6)} -------`
-  );
-  for (const r of rows) {
-    // status has ANSI codes so pad the raw length
+    const url =
+      inst.status === "running"
+        ? dashboardURL(host, inst.port, inst.gateway_token)
+        : c.dim("—");
     console.log(
-      `${r.name.padEnd(16)} ${r.status.padEnd(21)} ${String(r.port).padEnd(6)} ${r.created}`
+      `${name.padEnd(16)} ${statusCol.padEnd(21)} ${String(inst.port).padEnd(7)} ${url}`
     );
   }
 }
@@ -292,7 +340,10 @@ async function cmdStart(config: Config, args: string[]) {
   await docker("start", containerName(name));
   config.instances[name].status = "running";
   await saveConfig(config);
+  const host = getLanIP();
+  const inst = config.instances[name];
   ok(`Instance '${name}' started`);
+  console.log(`  ${c.bold("Dashboard:")} ${dashboardURL(host, inst.port, inst.gateway_token)}`);
 }
 
 async function cmdStop(config: Config, args: string[]) {
@@ -312,7 +363,10 @@ async function cmdRestart(config: Config, args: string[]) {
   await docker("restart", containerName(name));
   config.instances[name].status = "running";
   await saveConfig(config);
+  const host = getLanIP();
+  const inst = config.instances[name];
   ok(`Instance '${name}' restarted`);
+  console.log(`  ${c.bold("Dashboard:")} ${dashboardURL(host, inst.port, inst.gateway_token)}`);
 }
 
 async function cmdDelete(config: Config, args: string[]) {
@@ -350,15 +404,12 @@ async function cmdRename(config: Config, args: string[]) {
 
   info(`Renaming '${oldName}' → '${newName}'...`);
 
-  // Copy instance config
   const inst = { ...config.instances[oldName] };
   inst.name = newName;
   inst.volume = volumeName(newName);
 
-  // Stop old container
   await dockerQuiet("rm", "-f", containerName(oldName));
 
-  // Migrate volume
   const oldVol = volumeName(oldName);
   const newVol = volumeName(newName);
   await docker("volume", "create", newVol);
@@ -376,7 +427,6 @@ async function cmdRename(config: Config, args: string[]) {
   );
   await dockerQuiet("volume", "rm", oldVol);
 
-  // Update config and rebuild
   delete config.instances[oldName];
   config.instances[newName] = inst;
   await rebuildContainer(config, newName);
@@ -388,7 +438,7 @@ async function cmdRename(config: Config, args: string[]) {
 async function cmdConfig(config: Config, args: string[]) {
   const name = args[0];
   if (!name || name.startsWith("-"))
-    die("usage: clawpool config <name> [-t <token>] [-e KEY=VAL ...]");
+    die("usage: clawpool config <name> [--telegram-token <token>] [-e KEY=VAL ...]");
 
   requireInstance(config, name);
   const inst = config.instances[name];
@@ -396,10 +446,9 @@ async function cmdConfig(config: Config, args: string[]) {
 
   for (let i = 1; i < args.length; i++) {
     switch (args[i]) {
-      case "-t":
-      case "--token":
+      case "--telegram-token":
         inst.telegram_bot_token = args[++i];
-        info("Token updated");
+        info("Telegram token updated");
         changed = true;
         break;
       case "-e":
@@ -417,7 +466,7 @@ async function cmdConfig(config: Config, args: string[]) {
     }
   }
 
-  if (!changed) die("nothing to change — specify --token or --env");
+  if (!changed) die("nothing to change — specify --telegram-token or --env");
 
   info("Rebuilding container...");
   await rebuildContainer(config, name);
@@ -426,10 +475,10 @@ async function cmdConfig(config: Config, args: string[]) {
 }
 
 async function cmdLogs(config: Config, args: string[]) {
-  const name = args.find((a): a is string => !a.startsWith("-"));
-  if (!name) return die("usage: clawpool logs <name> [-f]");
+  const name = args[0];
+  if (!name || name.startsWith("-")) return die("usage: clawpool logs <name> [-f] [--tail N]");
   requireInstance(config, name);
-  const flags = args.filter((a) => a.startsWith("-"));
+  const flags = args.slice(1);
   await dockerExec("logs", ...flags, containerName(name));
 }
 
@@ -447,14 +496,18 @@ async function cmdStatus(config: Config, args: string[]) {
         ? c.red(inst.status)
         : c.yellow(inst.status);
 
+  const host = getLanIP();
   console.log(`${c.bold("Instance:")} ${inst.name}`);
   console.log(`${c.bold("Status:")}   ${statusCol}`);
   console.log(`${c.bold("Port:")}     ${inst.port}`);
   console.log(`${c.bold("Volume:")}   ${inst.volume}`);
   console.log(`${c.bold("Created:")}  ${inst.created_at}`);
-  console.log(
-    `${c.bold("Token:")}    ${inst.telegram_bot_token.slice(0, 20)}...`
-  );
+  if (inst.status === "running") {
+    console.log(`${c.bold("Dashboard:")} ${dashboardURL(host, inst.port, inst.gateway_token)}`);
+  }
+  if (inst.telegram_bot_token) {
+    console.log(`${c.bold("Telegram:")} configured`);
+  }
 
   const envKeys = Object.keys(inst.env);
   if (envKeys.length > 0) {
@@ -500,31 +553,35 @@ function cmdHelp() {
   console.log(`clawpool — Manage OpenClaw container instances
 
 Usage:
-  clawpool create <name> -t <telegram_bot_token> [-p <port>] [-e KEY=VAL ...]
+  clawpool create <name> [--telegram-token <token>] [-p <port>] [-e KEY=VAL ...]
   clawpool list [--json]
   clawpool start <name>
   clawpool stop <name>
   clawpool restart <name>
   clawpool delete <name> [--purge]
   clawpool rename <old_name> <new_name>
-  clawpool config <name> [-t <new_token>] [-e KEY=VAL ...]
+  clawpool config <name> [--telegram-token <token>] [-e KEY=VAL ...]
   clawpool logs <name> [-f]
   clawpool status <name>
   clawpool shell <name>
   clawpool image [set <image> | show]
 
 Options:
-  -t, --token   Telegram bot token
-  -p, --port    Host port (auto-assigned if omitted)
-  -e, --env     Extra environment variable (repeatable)
-  --purge       Also remove data volume on delete
-  --json        Output in JSON format
+  --telegram-token  Telegram bot token (optional)
+  -p, --port        Host port (auto-assigned from ${BASE_PORT}, step ${PORT_STEP})
+  -e, --env         Extra environment variable (repeatable)
+  --purge           Also remove data volume on delete
+  --json            Output in JSON format
+
+Each instance gets a Web Dashboard URL with an auto-generated auth token.
+Access it from any browser on your local network.
 
 Examples:
-  clawpool create alpha -t "123456:AAH..." -e "OPENAI_API_KEY=sk-..."
+  clawpool create alpha
+  clawpool create beta -e "OPENAI_API_KEY=sk-..."
+  clawpool create gamma --telegram-token "123456:AAH..."
   clawpool list
   clawpool logs alpha -f
-  clawpool config alpha -t "new_token"
   clawpool delete alpha --purge`);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linkclaw/clawpool",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "bin": {
     "clawpool": "./clawpool.ts"
@@ -24,5 +24,5 @@
     "url": "https://github.com/linkclaw-lab/clawpool.git"
   },
   "license": "MIT",
-  "description": "CLI tool to manage OpenClaw container instances with Telegram integration"
+  "description": "CLI tool to manage OpenClaw container instances with Web Dashboard"
 }