@linkclaw/clawpool 0.1.0

package/README.md

@@ -0,0 +1,107 @@
+# clawpool
+
+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.
+
+## Prerequisites
+
+```bash
+brew install colima docker bun
+
+# Start Colima (first time)
+colima start --cpu 8 --memory 12 --disk 100 --vm-type vz
+
+# Auto-start on boot
+brew services start colima
+```
+
+## Install
+
+```bash
+# Via npx (no install needed)
+npx @linkclaw/clawpool list
+
+# Or install globally
+npm i -g @linkclaw/clawpool
+clawpool list
+```
+
+## Usage
+
+```
+clawpool create <name> -t <telegram_bot_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 logs <name> [-f]
+clawpool status <name>
+clawpool shell <name>
+clawpool image [set <image> | show]
+```
+
+## Quick Start
+
+```bash
+# 1. Build or pull the OpenClaw image
+docker build -t openclaw:latest /path/to/apps/agent
+
+# 2. Create an instance with a Telegram bot token
+clawpool create alpha -t "123456:AAHxxx..."
+
+# 3. Add another instance with extra env vars
+clawpool create beta -t "789012:BBXyyy..." -e "OPENAI_API_KEY=sk-..."
+
+# 4. Check running instances
+clawpool list
+
+# 5. View logs
+clawpool logs alpha -f
+
+# 6. Reconfigure
+clawpool config alpha -t "new_token_here"
+
+# 7. Clean up
+clawpool delete beta --purge
+```
+
+## How It Works
+
+- **Config**: `~/.clawpool/config.json` stores instance metadata (name, port, token, env vars).
+- **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).
+
+## Config File
+
+Stored at `~/.clawpool/config.json`:
+
+```jsonc
+{
+  "image": "openclaw:latest",   // default image for new instances
+  "next_port": 8083,            // next auto-assigned port
+  "instances": {
+    "alpha": {
+      "name": "alpha",
+      "port": 8081,
+      "telegram_bot_token": "123456:AAH...",
+      "status": "running",
+      "container_id": "a1b2c3...",
+      "volume": "claw-alpha-data",
+      "env": { "OPENAI_API_KEY": "sk-..." },
+      "created_at": "2026-03-19T10:00:00Z"
+    }
+  }
+}
+```
+
+## Environment
+
+| Variable | Purpose |
+|---|---|
+| `CLAWPOOL_DIR` | Override config directory (default: `~/.clawpool`) |

package/clawpool.ts

@@ -0,0 +1,583 @@
+#!/usr/bin/env bun
+
+import { existsSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+// ── Config ──────────────────────────────────────────────────────────────────
+
+const CLAWPOOL_DIR = process.env.CLAWPOOL_DIR ?? join(homedir(), ".clawpool");
+const CONFIG_FILE = join(CLAWPOOL_DIR, "config.json");
+const CONTAINER_PREFIX = "claw";
+
+interface Instance {
+  name: string;
+  port: number;
+  telegram_bot_token: string;
+  status: "running" | "stopped" | "removed";
+  container_id: string;
+  volume: string;
+  env: Record<string, string>;
+  created_at: string;
+}
+
+interface Config {
+  image: string;
+  next_port: number;
+  instances: Record<string, Instance>;
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+const c = {
+  red: (s: string) => `\x1b[31m${s}\x1b[0m`,
+  green: (s: string) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s: string) => `\x1b[33m${s}\x1b[0m`,
+  cyan: (s: string) => `\x1b[36m${s}\x1b[0m`,
+  bold: (s: string) => `\x1b[1m${s}\x1b[0m`,
+};
+
+const die = (msg: string): never => {
+  console.error(`${c.red("Error:")} ${msg}`);
+  process.exit(1);
+};
+const info = (msg: string) => console.log(`${c.cyan("==>")} ${msg}`);
+const ok = (msg: string) => console.log(`${c.green("✓")} ${msg}`);
+
+const containerName = (name: string) => `${CONTAINER_PREFIX}-${name}`;
+const volumeName = (name: string) => `${CONTAINER_PREFIX}-${name}-data`;
+
+function humanTime(iso: string): string {
+  const diff = Math.floor((Date.now() - new Date(iso).getTime()) / 1000);
+  if (diff < 60) return `${diff}s ago`;
+  if (diff < 3600) return `${Math.floor(diff / 60)}m ago`;
+  if (diff < 86400) return `${Math.floor(diff / 3600)}h ago`;
+  return `${Math.floor(diff / 86400)}d ago`;
+}
+
+// ── Config I/O ──────────────────────────────────────────────────────────────
+
+async function loadConfig(): Promise<Config> {
+  mkdirSync(CLAWPOOL_DIR, { recursive: true });
+  if (!existsSync(CONFIG_FILE)) {
+    const initial: Config = {
+      image: "openclaw:latest",
+      next_port: 8081,
+      instances: {},
+    };
+    await Bun.write(CONFIG_FILE, JSON.stringify(initial, null, 2));
+    return initial;
+  }
+  return Bun.file(CONFIG_FILE).json();
+}
+
+async function saveConfig(config: Config) {
+  await Bun.write(CONFIG_FILE, JSON.stringify(config, null, 2));
+}
+
+function requireInstance(config: Config, name: string): Instance {
+  const inst = config.instances[name];
+  if (!inst) die(`instance '${name}' does not exist`);
+  return inst;
+}
+
+// ── Docker helpers ──────────────────────────────────────────────────────────
+
+async function docker(...args: string[]): Promise<string> {
+  const proc = Bun.spawn(["docker", ...args], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  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`);
+  return stdout.trim();
+}
+
+async function dockerQuiet(...args: string[]): Promise<boolean> {
+  const proc = Bun.spawn(["docker", ...args], {
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+  return (await proc.exited) === 0;
+}
+
+async function dockerExec(...args: string[]): Promise<void> {
+  const proc = Bun.spawn(["docker", ...args], {
+    stdout: "inherit",
+    stderr: "inherit",
+    stdin: "inherit",
+  });
+  await proc.exited;
+}
+
+async function syncStatus(
+  config: Config,
+  name: string
+): Promise<"running" | "stopped" | "removed"> {
+  try {
+    const state = await docker(
+      "inspect",
+      "-f",
+      "{{.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";
+  } catch {
+    config.instances[name].status = "removed";
+    return "removed";
+  }
+}
+
+function buildEnvArgs(inst: Instance): string[] {
+  const args = [
+    "-e",
+    `TELEGRAM_BOT_TOKEN=${inst.telegram_bot_token}`,
+    "-e",
+    `INSTANCE_NAME=${inst.name}`,
+  ];
+  for (const [k, v] of Object.entries(inst.env)) {
+    args.push("-e", `${k}=${v}`);
+  }
+  return args;
+}
+
+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"
+  );
+
+  inst.container_id = cid;
+  inst.status = "running";
+  return cid;
+}
+
+// ── Commands ────────────────────────────────────────────────────────────────
+
+async function cmdCreate(config: Config, args: string[]) {
+  let name = "";
+  let token = "";
+  let port = 0;
+  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 "-e":
+      case "--env": {
+        const kv = args[++i];
+        const eq = kv.indexOf("=");
+        if (eq === -1) die(`invalid env format: ${kv} (expected KEY=VAL)`);
+        env[kv.slice(0, eq)] = kv.slice(eq + 1);
+        break;
+      }
+      default:
+        if (args[i].startsWith("-")) die(`unknown option: ${args[i]}`);
+        if (!name) name = args[i];
+        else die(`unexpected argument: ${args[i]}`);
+    }
+  }
+
+  if (!name || !token) die("usage: clawpool create <name> -t <token>");
+  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;
+
+  info(`Creating instance '${name}' on port ${port}...`);
+
+  await docker("volume", "create", volumeName(name));
+
+  const inst: Instance = {
+    name,
+    port,
+    telegram_bot_token: token,
+    status: "running",
+    container_id: "",
+    volume: volumeName(name),
+    env,
+    created_at: new Date().toISOString(),
+  };
+
+  config.instances[name] = inst;
+  if (config.next_port <= port) config.next_port = port + 1;
+
+  const cid = await rebuildContainer(config, name);
+  await saveConfig(config);
+
+  ok(`Instance '${name}' created (port: ${port}, container: ${cid.slice(0, 12)})`);
+}
+
+async function cmdList(config: Config, args: string[]) {
+  const jsonMode = args.includes("--json");
+  const names = Object.keys(config.instances);
+
+  if (names.length === 0) {
+    console.log(
+      "No instances. Create one with: clawpool create <name> -t <token>"
+    );
+    return;
+  }
+
+  for (const name of names) await syncStatus(config, name);
+  await saveConfig(config);
+
+  if (jsonMode) {
+    console.log(JSON.stringify(config.instances, null, 2));
+    return;
+  }
+
+  const rows = names.map((name) => {
+    const inst = config.instances[name];
+    const statusCol =
+      inst.status === "running"
+        ? c.green(inst.status)
+        : 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
+    console.log(
+      `${r.name.padEnd(16)} ${r.status.padEnd(21)} ${String(r.port).padEnd(6)} ${r.created}`
+    );
+  }
+}
+
+async function cmdStart(config: Config, args: string[]) {
+  const name = args[0] ?? die("usage: clawpool start <name>");
+  requireInstance(config, name);
+  info(`Starting '${name}'...`);
+  await docker("start", containerName(name));
+  config.instances[name].status = "running";
+  await saveConfig(config);
+  ok(`Instance '${name}' started`);
+}
+
+async function cmdStop(config: Config, args: string[]) {
+  const name = args[0] ?? die("usage: clawpool stop <name>");
+  requireInstance(config, name);
+  info(`Stopping '${name}'...`);
+  await docker("stop", containerName(name));
+  config.instances[name].status = "stopped";
+  await saveConfig(config);
+  ok(`Instance '${name}' stopped`);
+}
+
+async function cmdRestart(config: Config, args: string[]) {
+  const name = args[0] ?? die("usage: clawpool restart <name>");
+  requireInstance(config, name);
+  info(`Restarting '${name}'...`);
+  await docker("restart", containerName(name));
+  config.instances[name].status = "running";
+  await saveConfig(config);
+  ok(`Instance '${name}' restarted`);
+}
+
+async function cmdDelete(config: Config, args: string[]) {
+  let name = "";
+  let purge = false;
+  for (const a of args) {
+    if (a === "--purge") purge = true;
+    else if (!a.startsWith("-")) name = a;
+    else die(`unknown option: ${a}`);
+  }
+  if (!name) die("usage: clawpool delete <name> [--purge]");
+  requireInstance(config, name);
+
+  info(`Deleting '${name}'...`);
+  await dockerQuiet("rm", "-f", containerName(name));
+
+  if (purge) {
+    await dockerQuiet("volume", "rm", volumeName(name));
+    info("Volume purged");
+  }
+
+  delete config.instances[name];
+  await saveConfig(config);
+  ok(`Instance '${name}' deleted`);
+}
+
+async function cmdRename(config: Config, args: string[]) {
+  const oldName = args[0] ?? die("usage: clawpool rename <old> <new>");
+  const newName = args[1] ?? die("usage: clawpool rename <old> <new>");
+
+  requireInstance(config, oldName);
+  if (config.instances[newName]) die(`instance '${newName}' already exists`);
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(newName))
+    die("invalid name: use alphanumerics, dots, hyphens, underscores");
+
+  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);
+  await dockerQuiet(
+    "run",
+    "--rm",
+    "-v",
+    `${oldVol}:/from`,
+    "-v",
+    `${newVol}:/to`,
+    "alpine",
+    "sh",
+    "-c",
+    "cp -a /from/. /to/"
+  );
+  await dockerQuiet("volume", "rm", oldVol);
+
+  // Update config and rebuild
+  delete config.instances[oldName];
+  config.instances[newName] = inst;
+  await rebuildContainer(config, newName);
+  await saveConfig(config);
+
+  ok(`Renamed '${oldName}' → '${newName}'`);
+}
+
+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 ...]");
+
+  requireInstance(config, name);
+  const inst = config.instances[name];
+  let changed = false;
+
+  for (let i = 1; i < args.length; i++) {
+    switch (args[i]) {
+      case "-t":
+      case "--token":
+        inst.telegram_bot_token = args[++i];
+        info("Token updated");
+        changed = true;
+        break;
+      case "-e":
+      case "--env": {
+        const kv = args[++i];
+        const eq = kv.indexOf("=");
+        if (eq === -1) die(`invalid env format: ${kv}`);
+        inst.env[kv.slice(0, eq)] = kv.slice(eq + 1);
+        info(`Env ${kv.slice(0, eq)} set`);
+        changed = true;
+        break;
+      }
+      default:
+        die(`unknown option: ${args[i]}`);
+    }
+  }
+
+  if (!changed) die("nothing to change — specify --token or --env");
+
+  info("Rebuilding container...");
+  await rebuildContainer(config, name);
+  await saveConfig(config);
+  ok(`Instance '${name}' reconfigured and restarted`);
+}
+
+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]");
+  requireInstance(config, name);
+  const flags = args.filter((a) => a.startsWith("-"));
+  await dockerExec("logs", ...flags, containerName(name));
+}
+
+async function cmdStatus(config: Config, args: string[]) {
+  const name = args[0] ?? die("usage: clawpool status <name>");
+  requireInstance(config, name);
+  await syncStatus(config, name);
+  await saveConfig(config);
+
+  const inst = config.instances[name];
+  const statusCol =
+    inst.status === "running"
+      ? c.green(inst.status)
+      : inst.status === "stopped"
+        ? c.red(inst.status)
+        : c.yellow(inst.status);
+
+  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)}...`
+  );
+
+  const envKeys = Object.keys(inst.env);
+  if (envKeys.length > 0) {
+    console.log(`${c.bold("Env vars:")} ${envKeys.length}`);
+    for (const [k, v] of Object.entries(inst.env)) {
+      console.log(`  ${k}=${v.slice(0, 20)}...`);
+    }
+  }
+
+  if (inst.status === "running") {
+    console.log("");
+    await dockerExec(
+      "stats",
+      "--no-stream",
+      "--format",
+      `${c.bold("CPU:")} {{.CPUPerc}}  ${c.bold("Mem:")} {{.MemUsage}}`,
+      containerName(name)
+    );
+  }
+}
+
+async function cmdShell(config: Config, args: string[]) {
+  const name = args[0] ?? die("usage: clawpool shell <name>");
+  requireInstance(config, name);
+  await dockerExec("exec", "-it", containerName(name), "/bin/sh");
+}
+
+async function cmdImage(config: Config, args: string[]) {
+  const sub = args[0] ?? "show";
+  if (sub === "set") {
+    const img = args[1] ?? die("usage: clawpool image set <image>");
+    config.image = img;
+    await saveConfig(config);
+    ok(`Default image set to '${img}'`);
+  } else if (sub === "show") {
+    console.log(config.image);
+  } else {
+    die("usage: clawpool image [set <image> | show]");
+  }
+}
+
+function cmdHelp() {
+  console.log(`clawpool — Manage OpenClaw container instances
+
+Usage:
+  clawpool create <name> -t <telegram_bot_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 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
+
+Examples:
+  clawpool create alpha -t "123456:AAH..." -e "OPENAI_API_KEY=sk-..."
+  clawpool list
+  clawpool logs alpha -f
+  clawpool config alpha -t "new_token"
+  clawpool delete alpha --purge`);
+}
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+const config = await loadConfig();
+const [cmd, ...args] = process.argv.slice(2);
+
+switch (cmd ?? "help") {
+  case "create":
+    await cmdCreate(config, args);
+    break;
+  case "list":
+  case "ls":
+    await cmdList(config, args);
+    break;
+  case "start":
+    await cmdStart(config, args);
+    break;
+  case "stop":
+    await cmdStop(config, args);
+    break;
+  case "restart":
+    await cmdRestart(config, args);
+    break;
+  case "delete":
+  case "rm":
+    await cmdDelete(config, args);
+    break;
+  case "rename":
+    await cmdRename(config, args);
+    break;
+  case "config":
+    await cmdConfig(config, args);
+    break;
+  case "logs":
+    await cmdLogs(config, args);
+    break;
+  case "status":
+    await cmdStatus(config, args);
+    break;
+  case "shell":
+  case "sh":
+    await cmdShell(config, args);
+    break;
+  case "image":
+    await cmdImage(config, args);
+    break;
+  case "help":
+  case "-h":
+  case "--help":
+    cmdHelp();
+    break;
+  default:
+    die(`unknown command: ${cmd} (run 'clawpool help' for usage)`);
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@linkclaw/clawpool",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "clawpool": "./clawpool.ts"
+  },
+  "files": [
+    "clawpool.ts"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "start": "bun run clawpool.ts"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "^5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/linkclaw-lab/clawpool.git"
+  },
+  "license": "MIT",
+  "description": "CLI tool to manage OpenClaw container instances with Telegram integration"
+}