fireclaw 0.1.0

package/README.md

@@ -0,0 +1,178 @@
+# fireclaw-vm-demo
+
+Run [OpenClaw](https://github.com/openclaw/openclaw) instances inside Firecracker microVMs, each fully isolated with its own filesystem, network, and process tree.
+
+## Why
+
+Running OpenClaw directly on a host (bare metal or in Docker) means every instance shares the kernel, network namespace, and often the Docker socket. That's fine for a single bot, but problematic when you want:
+
+- **Isolation** — one misbehaving instance can't interfere with others or the host
+- **Reproducibility** — each VM boots from a clean rootfs image, no drift
+- **Security** — no Docker socket mount into the container; the guest runs its own Docker daemon
+- **Density** — Firecracker VMs boot in ~125ms and use ~5MB overhead per VM, so you can pack many instances on a single host
+
+This repo is a minimal control plane that wires up Firecracker VM lifecycle, networking, and OpenClaw provisioning with plain bash and systemd. No orchestrator, no Kubernetes, no extra daemons.
+
+## How it works
+
+```
+Host
+├── systemd: firecracker-vmdemo-<id>.service   ← runs the VM
+├── systemd: vmdemo-proxy-<id>.service          ← socat: localhost:<port> → VM:18789
+├── bridge: fcbr0 (172.16.0.0/24)              ← shared bridge for all VMs
+│
+└── Firecracker VM (172.16.0.x)
+    ├── cloud-init: ubuntu user, SSH key, Docker install
+    ├── Docker: pulls OpenClaw image
+    ├── systemd: openclaw-<id>.service          ← docker run --network host ... gateway --bind lan --port 18789
+    └── Browser binaries (Playwright Chromium, installed at provision time)
+```
+
+1. **`fireclaw setup`** creates a new instance: copies the base rootfs, optionally resizes it (default `40G`), generates a cloud-init seed image, allocates an IP + host port, writes a Firecracker config, creates systemd units, boots the VM with a per-instance Firecracker API socket, waits for SSH, then SCPs `provision-guest.sh` into the guest and runs it.
+
+2. **`provision-guest.sh`** runs inside the VM as root: waits for cloud-init/apt locks, expands the guest ext4 filesystem (`resize2fs`), configures Docker for Firecracker (`iptables=false`, `ip6tables=false`, `bridge=none`), pulls the OpenClaw image, runs the OpenClaw CLI (`doctor --fix` included), installs Playwright Chromium, writes browser path + health-check script, then creates and starts the guest systemd service.
+
+3. **`fireclaw`** manages lifecycle after setup: start/stop/restart VMs, tail logs (guest or host side), open an SSH shell, show status, or destroy an instance.
+
+All state lives in two places:
+- **Repo-local** `.vm-demo/.vm-<id>/` — env file, token, provision vars
+- **Host filesystem** `/srv/firecracker/vm-demo/<id>/` — VM images, Firecracker config, logs
+
+## Prerequisites
+
+- Linux host with KVM support (`/dev/kvm` accessible)
+- `firecracker` binary at `/usr/local/bin/firecracker` ([install guide](https://github.com/firecracker-microvm/firecracker/blob/main/docs/getting-started.md))
+- `qemu-img` (from `qemu-utils`) for rootfs resizing
+- `cloud-localds` (from `cloud-image-utils`), `socat`, `jq`, `iptables`, `iproute2`, `ssh`, `scp`, `curl`, `openssl`
+- Base VM images: a Linux kernel (`vmlinux`) and an ext4 rootfs with cloud-init support. Optionally an initrd.
+
+Set `BASE_IMAGES_DIR` or pass `--base-kernel`/`--base-rootfs`/`--base-initrd` to point at your images.
+
+## Setup
+
+```bash
+# 1. Clone
+git clone https://github.com/bchewy/fireclaw-vm-demo.git
+cd fireclaw-vm-demo
+
+# 2. (Optional) install global CLI
+sudo install -m 0755 ./bin/fireclaw /usr/local/bin/fireclaw
+
+# 3. Create an instance
+sudo fireclaw setup \
+  --instance my-bot \
+  --telegram-token "<your-bot-token>" \
+  --telegram-users "<your-telegram-user-id>" \
+  --model "anthropic/claude-opus-4-6" \
+  --anthropic-api-key "<key>"
+```
+
+## Install From npm
+
+```bash
+# Global install
+sudo npm install -g fireclaw
+
+# Then use:
+sudo fireclaw --help
+sudo fireclaw list
+```
+
+## Publish To npm
+
+```bash
+# 1. Login/check auth
+npm login
+npm whoami
+
+# 2. Validate package contents and scripts
+npm test
+npm pack --dry-run
+
+# 3. Bump version and publish
+npm version patch
+npm publish
+```
+
+If `npm publish` fails because the package name is unavailable, change `"name"` in `package.json` (for example to a scoped package like `@<your-scope>/fireclaw`) and publish again.
+
+### Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--instance` | (required) | Instance ID (`[a-z0-9_-]+`) |
+| `--telegram-token` | (required) | Telegram bot token |
+| `--telegram-users` | | Comma-separated Telegram user IDs for allowlist |
+| `--model` | `anthropic/claude-opus-4-6` | Model ID |
+| `--skills` | `github,tmux,coding-agent,session-logs,skill-creator` | Comma-separated skill list |
+| `--openclaw-image` | `ghcr.io/openclaw/openclaw:latest` | Docker image for OpenClaw |
+| `--vm-vcpu` | `4` | vCPUs per VM |
+| `--vm-mem-mib` | `8192` | Memory per VM (MiB) |
+| `--disk-size` | `40G` | Resize copied rootfs image to this virtual size before boot |
+| `--api-sock` | `<fc-dir>/firecracker.socket` | Firecracker API socket path (must be unique per VM) |
+| `--anthropic-api-key` | | Anthropic API key |
+| `--openai-api-key` | | OpenAI API key |
+| `--minimax-api-key` | | MiniMax API key |
+| `--skip-browser-install` | `false` | Skip Playwright Chromium install |
+
+## Usage
+
+```bash
+# List all instances
+sudo fireclaw list
+
+# Status of one instance
+sudo fireclaw status my-bot
+
+# Stop / start / restart
+sudo fireclaw stop my-bot
+sudo fireclaw start my-bot
+sudo fireclaw restart my-bot
+
+# Tail guest logs (OpenClaw service)
+sudo fireclaw logs my-bot
+
+# Tail host logs (Firecracker + proxy)
+sudo fireclaw logs my-bot host
+
+# SSH into the VM
+sudo fireclaw shell my-bot
+
+# Run a command inside the VM
+sudo fireclaw shell my-bot "docker ps"
+
+# Get the gateway token
+sudo fireclaw token my-bot
+
+# Health check
+curl -fsS http://127.0.0.1:<HOST_PORT>/health
+# If proxy health is flaky, inspect VM-side health too:
+sudo fireclaw status my-bot
+
+# Destroy (interactive confirmation)
+sudo fireclaw destroy my-bot
+
+# Destroy (skip confirmation)
+sudo fireclaw destroy my-bot --force
+```
+
+## Networking
+
+Each VM gets a static IP on a bridge (`fcbr0`, `172.16.0.0/24`). The host acts as the gateway at `172.16.0.1` with NAT for outbound traffic. A `socat` proxy on the host forwards `127.0.0.1:<HOST_PORT>` to the VM's gateway port (`18789`), so the OpenClaw API is only reachable from localhost.
+
+## Environment variables
+
+All scripts respect these overrides:
+
+| Variable | Default |
+|----------|---------|
+| `STATE_ROOT` | `<repo>/.vm-demo` |
+| `FC_ROOT` | `/srv/firecracker/vm-demo` |
+| `BASE_PORT` | `18890` |
+| `BRIDGE_NAME` | `fcbr0` |
+| `BRIDGE_ADDR` | `172.16.0.1/24` |
+| `SUBNET_CIDR` | `172.16.0.0/24` |
+| `SSH_KEY_PATH` | `~/.ssh/vmdemo_vm` |
+| `BASE_IMAGES_DIR` | `/srv/firecracker/base/images` |
+| `DISK_SIZE` | `40G` |
+| `API_SOCK` | `<FC_ROOT>/<instance>/firecracker.socket` |

package/bin/fireclaw

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+usage() {
+  cat <<'EOF'
+Usage: fireclaw <command> [args...]
+
+Primary commands:
+  setup <flags...>                    Create and provision a new VM instance
+  list                                List instances
+  status [id]                         Show instance status
+  start <id>                          Start instance
+  stop <id>                           Stop instance
+  restart <id>                        Restart instance
+  logs <id> [guest|host]              Stream logs
+  shell <id> [command...]             SSH shell or run command in VM
+  token <id>                          Show gateway token
+  destroy <id> [--force]              Destroy instance
+
+Compatibility commands:
+  ctl <vm-ctl-args...>                Pass through to vm-ctl
+  vm-setup <flags...>                 Pass through to vm-setup
+  vm-ctl <args...>                    Pass through to vm-ctl
+
+Examples:
+  sudo ./bin/fireclaw setup --instance my-bot --telegram-token <token> --telegram-users <uid>
+  sudo ./bin/fireclaw list
+  sudo ./bin/fireclaw status my-bot
+EOF
+}
+
+[[ $# -ge 1 ]] || {
+  usage
+  exit 1
+}
+
+cmd="$1"
+shift || true
+
+case "$cmd" in
+  setup|create|provision)
+    VM_SETUP_CMD_NAME="fireclaw setup" exec "$SCRIPT_DIR/vm-setup" "$@"
+    ;;
+  list|status|start|stop|restart|logs|shell|token|destroy)
+    if [[ "${1:-}" == "-h" || "${1:-}" == "--help" || "${1:-}" == "help" ]]; then
+      VM_CTL_CMD_NAME="fireclaw" exec "$SCRIPT_DIR/vm-ctl" --help
+    fi
+    VM_CTL_CMD_NAME="fireclaw" exec "$SCRIPT_DIR/vm-ctl" "$cmd" "$@"
+    ;;
+  ctl|vm-ctl)
+    VM_CTL_CMD_NAME="fireclaw ctl" exec "$SCRIPT_DIR/vm-ctl" "$@"
+    ;;
+  vm-setup)
+    VM_SETUP_CMD_NAME="fireclaw vm-setup" exec "$SCRIPT_DIR/vm-setup" "$@"
+    ;;
+  help|-h|--help)
+    usage
+    ;;
+  *)
+    echo "Error: unknown command '$cmd'" >&2
+    usage
+    exit 1
+    ;;
+esac

package/bin/vm-common.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="${REPO_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+STATE_ROOT="${STATE_ROOT:-$REPO_ROOT/.vm-demo}"
+FC_ROOT="${FC_ROOT:-/srv/firecracker/vm-demo}"
+BASE_PORT="${BASE_PORT:-18890}"
+
+BRIDGE_NAME="${BRIDGE_NAME:-fcbr0}"
+BRIDGE_ADDR="${BRIDGE_ADDR:-172.16.0.1/24}"
+SUBNET_CIDR="${SUBNET_CIDR:-172.16.0.0/24}"
+
+OPENCLAW_IMAGE_DEFAULT="${OPENCLAW_IMAGE_DEFAULT:-ghcr.io/openclaw/openclaw:latest}"
+SSH_KEY_PATH="${SSH_KEY_PATH:-$HOME/.ssh/vmdemo_vm}"
+
+log()  { printf '==> %s\n' "$*"; }
+warn() { printf 'Warning: %s\n' "$*" >&2; }
+die()  { printf 'Error: %s\n' "$*" >&2; exit 1; }
+
+require_cmd() { command -v "$1" >/dev/null 2>&1 || die "Missing command: $1"; }
+require_root() { [[ $EUID -eq 0 ]] || die "Run as root"; }
+
+ensure_root_dirs() { mkdir -p "$STATE_ROOT" "$FC_ROOT"; }
+
+validate_instance_id() {
+  local id="$1"
+  [[ -n "$id" ]] || die "instance id is required"
+  [[ "$id" =~ ^[a-z0-9_-]+$ ]] || die "instance id must match [a-z0-9_-]+"
+}
+
+instance_dir()      { printf '%s/.vm-%s\n' "$STATE_ROOT" "$1"; }
+instance_env()      { printf '%s/.env\n' "$(instance_dir "$1")"; }
+instance_token()    { printf '%s/.token\n' "$(instance_dir "$1")"; }
+fc_instance_dir()   { printf '%s/%s\n' "$FC_ROOT" "$1"; }
+vm_service()        { printf 'firecracker-vmdemo-%s.service\n' "$1"; }
+proxy_service()     { printf 'vmdemo-proxy-%s.service\n' "$1"; }
+guest_health_script() { printf '/usr/local/bin/openclaw-health-%s.sh\n' "$1"; }
+
+load_instance_env() {
+  local id="$1"
+  validate_instance_id "$id"
+  local f
+  f="$(instance_env "$id")"
+  [[ -f "$f" ]] || die "instance '$id' not found"
+  set -a
+  source "$f"
+  set +a
+}
+
+next_port() {
+  local max="$BASE_PORT"
+  shopt -s nullglob
+  local f p
+  for f in "$STATE_ROOT"/.vm-*/.env; do
+    p="$(grep '^HOST_PORT=' "$f" | cut -d= -f2 || true)"
+    if [[ -n "${p:-}" && "$p" -gt "$max" ]]; then
+      max="$p"
+    fi
+  done
+  shopt -u nullglob
+  echo $((max + 1))
+}
+
+next_ip() {
+  local max_octet=1
+  shopt -s nullglob
+  local f ip oct
+  for f in "$STATE_ROOT"/.vm-*/.env; do
+    ip="$(grep '^VM_IP=' "$f" | cut -d= -f2 || true)"
+    oct="${ip##*.}"
+    if [[ "$oct" =~ ^[0-9]+$ ]] && (( oct > max_octet )); then
+      max_octet="$oct"
+    fi
+  done
+  shopt -u nullglob
+
+  local next=$((max_octet + 1))
+  (( next < 255 )) || die "IP pool exhausted"
+  echo "172.16.0.$next"
+}
+
+ensure_bridge_and_nat() {
+  if ! ip link show "$BRIDGE_NAME" >/dev/null 2>&1; then
+    ip link add "$BRIDGE_NAME" type bridge
+  fi
+  ip addr add "$BRIDGE_ADDR" dev "$BRIDGE_NAME" 2>/dev/null || true
+  ip link set "$BRIDGE_NAME" up
+
+  sysctl -w net.ipv4.ip_forward=1 >/dev/null
+
+  iptables -t nat -C POSTROUTING -s "$SUBNET_CIDR" ! -o "$BRIDGE_NAME" -j MASQUERADE 2>/dev/null \
+    || iptables -t nat -A POSTROUTING -s "$SUBNET_CIDR" ! -o "$BRIDGE_NAME" -j MASQUERADE
+}
+
+wait_for_ssh() {
+  local ip="$1"
+  local key="${2:-$SSH_KEY_PATH}"
+  local retries="${3:-120}"
+  local i
+  for ((i=1; i<=retries; i++)); do
+    if ssh -i "$key" -o StrictHostKeyChecking=accept-new -o UserKnownHostsFile=/dev/null -o ConnectTimeout=3 "ubuntu@$ip" true >/dev/null 2>&1; then
+      return 0
+    fi
+    sleep 2
+  done
+  return 1
+}
+
+check_guest_health() {
+  local id="$1"
+  local ip="$2"
+  local key="${3:-$SSH_KEY_PATH}"
+  local script
+  script="$(guest_health_script "$id")"
+  ssh -i "$key" -o StrictHostKeyChecking=accept-new -o UserKnownHostsFile=/dev/null -o ConnectTimeout=3 "ubuntu@$ip" "if [[ -x '$script' ]]; then sudo '$script'; else curl -fsS http://127.0.0.1:18789/health >/dev/null; fi" >/dev/null 2>&1
+}

package/bin/vm-ctl

@@ -0,0 +1,208 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/vm-common.sh"
+CMD_NAME="${VM_CTL_CMD_NAME:-$(basename "$0")}"
+
+usage() {
+  cat <<EOF
+Usage: $CMD_NAME <command> [instance]
+
+Commands:
+  list
+  status [id]
+  start <id>
+  stop <id>
+  restart <id>
+  logs <id> [guest|host]
+  shell <id> [command...]
+  token <id>
+  destroy <id> [--force]
+EOF
+}
+
+ssh_run() {
+  local ip="$1"; shift
+  local key="${SSH_KEY_PATH:-$HOME/.ssh/vmdemo_vm}"
+  ssh -i "$key" -o StrictHostKeyChecking=accept-new -o UserKnownHostsFile=/dev/null "ubuntu@$ip" "$@"
+}
+
+cmd_list() {
+  shopt -s nullglob
+  local found="false"
+  for d in "$STATE_ROOT"/.vm-*/; do
+    found="true"
+    local id
+    id="$(basename "$d" | sed 's/^\.vm-//')"
+    if [[ ! "$id" =~ ^[a-z0-9_-]+$ ]]; then
+      warn "Skipping invalid instance state directory: $d"
+      continue
+    fi
+    load_instance_env "$id"
+    local ssh_key="${SSH_KEY_PATH:-$HOME/.ssh/vmdemo_vm}"
+    local health="down"
+    local host_health="down"
+    local guest_health="down"
+    curl -fsS "http://127.0.0.1:$HOST_PORT/health" >/dev/null 2>&1 && host_health="up"
+    if check_guest_health "$id" "$VM_IP" "$ssh_key"; then
+      guest_health="up"
+    fi
+    if [[ "$host_health" == "up" || "$guest_health" == "up" ]]; then
+      health="up"
+    fi
+    local vm_state proxy_state
+    vm_state="$(systemctl is-active "$(vm_service "$id")" 2>/dev/null || echo inactive)"
+    proxy_state="$(systemctl is-active "$(proxy_service "$id")" 2>/dev/null || echo inactive)"
+    echo "$id ip=$VM_IP port=$HOST_PORT vm=$vm_state proxy=$proxy_state health=$health host_health=$host_health guest_health=$guest_health"
+  done
+  shopt -u nullglob
+  [[ "$found" == "true" ]] || echo "(no instances)"
+}
+
+cmd_status_one() {
+  local id="$1"
+  validate_instance_id "$id"
+  load_instance_env "$id"
+  local ssh_key="${SSH_KEY_PATH:-$HOME/.ssh/vmdemo_vm}"
+  local vm_state proxy_state health host_health guest_health guest
+  vm_state="$(systemctl is-active "$(vm_service "$id")" 2>/dev/null || echo inactive)"
+  proxy_state="$(systemctl is-active "$(proxy_service "$id")" 2>/dev/null || echo inactive)"
+  health="down"
+  host_health="down"
+  guest_health="down"
+  curl -fsS "http://127.0.0.1:$HOST_PORT/health" >/dev/null 2>&1 && host_health="up"
+  guest="unknown"
+  if wait_for_ssh "$VM_IP" "$ssh_key" 1; then
+    guest="$(ssh_run "$VM_IP" "systemctl is-active openclaw-$id.service" 2>/dev/null || echo unknown)"
+    if check_guest_health "$id" "$VM_IP" "$ssh_key"; then
+      guest_health="up"
+    fi
+  fi
+  if [[ "$host_health" == "up" || "$guest_health" == "up" ]]; then
+    health="up"
+  fi
+  echo "$id ip=$VM_IP port=$HOST_PORT vm=$vm_state proxy=$proxy_state guest=$guest health=$health host_health=$host_health guest_health=$guest_health"
+}
+
+cmd_status() {
+  if [[ $# -eq 1 ]]; then
+    cmd_status_one "$1"
+    return
+  fi
+  cmd_list
+}
+
+cmd_start() {
+  local id="$1"
+  validate_instance_id "$id"
+  require_root
+  load_instance_env "$id"
+
+  systemctl enable --now "$(vm_service "$id")"
+  wait_for_ssh "$VM_IP" "$SSH_KEY_PATH" 180 || die "VM started but SSH unreachable"
+
+  ssh_run "$VM_IP" "sudo systemctl enable --now openclaw-$id.service" || warn "Guest service start failed"
+  systemctl enable --now "$(proxy_service "$id")"
+
+  cmd_status_one "$id"
+}
+
+cmd_stop() {
+  local id="$1"
+  validate_instance_id "$id"
+  require_root
+  load_instance_env "$id"
+
+  systemctl stop "$(proxy_service "$id")" 2>/dev/null || true
+  if wait_for_ssh "$VM_IP" "$SSH_KEY_PATH" 1; then
+    ssh_run "$VM_IP" "sudo systemctl stop openclaw-$id.service" || true
+  fi
+  systemctl stop "$(vm_service "$id")"
+  cmd_status_one "$id"
+}
+
+cmd_restart() {
+  cmd_stop "$1"
+  cmd_start "$1"
+}
+
+cmd_logs() {
+  local id="$1"
+  local mode="${2:-guest}"
+  validate_instance_id "$id"
+  load_instance_env "$id"
+
+  if [[ "$mode" == "host" ]]; then
+    journalctl -u "$(vm_service "$id")" -u "$(proxy_service "$id")" -f
+    return
+  fi
+
+  wait_for_ssh "$VM_IP" "$SSH_KEY_PATH" 30 || die "VM SSH unavailable"
+  ssh_run "$VM_IP" "sudo journalctl -u openclaw-$id.service -f"
+}
+
+cmd_shell() {
+  local id="$1"
+  shift || true
+  validate_instance_id "$id"
+  load_instance_env "$id"
+  wait_for_ssh "$VM_IP" "$SSH_KEY_PATH" 30 || die "VM SSH unavailable"
+
+  if [[ $# -gt 0 ]]; then
+    ssh_run "$VM_IP" "$*"
+  else
+    ssh -i "$SSH_KEY_PATH" -o StrictHostKeyChecking=accept-new -o UserKnownHostsFile=/dev/null "ubuntu@$VM_IP"
+  fi
+}
+
+cmd_token() {
+  local id="$1"
+  validate_instance_id "$id"
+  cat "$(instance_token "$id")"
+}
+
+cmd_destroy() {
+  local id="$1"
+  local force="${2:-}"
+  validate_instance_id "$id"
+  require_root
+  load_instance_env "$id"
+
+  if [[ "$force" != "--force" ]]; then
+    read -r -p "Destroy '$id' and remove VM assets? [y/N] " confirm
+    [[ "$confirm" =~ ^[Yy]$ ]] || { echo "Cancelled"; return; }
+  fi
+
+  systemctl stop "$(proxy_service "$id")" 2>/dev/null || true
+  systemctl stop "$(vm_service "$id")" 2>/dev/null || true
+  systemctl disable "$(proxy_service "$id")" 2>/dev/null || true
+  systemctl disable "$(vm_service "$id")" 2>/dev/null || true
+
+  rm -f "/etc/systemd/system/$(proxy_service "$id")"
+  rm -f "/etc/systemd/system/$(vm_service "$id")"
+  systemctl daemon-reload
+
+  rm -rf "$(instance_dir "$id")" "$(fc_instance_dir "$id")"
+
+  echo "Destroyed: $id"
+}
+
+[[ $# -ge 1 ]] || { usage; exit 1; }
+
+cmd="$1"
+shift || true
+
+case "$cmd" in
+  list) cmd_list ;;
+  status) cmd_status "$@" ;;
+  start) [[ $# -eq 1 ]] || die "Usage: vm-ctl start <id>"; cmd_start "$1" ;;
+  stop) [[ $# -eq 1 ]] || die "Usage: vm-ctl stop <id>"; cmd_stop "$1" ;;
+  restart) [[ $# -eq 1 ]] || die "Usage: vm-ctl restart <id>"; cmd_restart "$1" ;;
+  logs) [[ $# -ge 1 ]] || die "Usage: vm-ctl logs <id> [guest|host]"; cmd_logs "$@" ;;
+  shell) [[ $# -ge 1 ]] || die "Usage: vm-ctl shell <id> [command...]"; id="$1"; shift; cmd_shell "$id" "$@" ;;
+  token) [[ $# -eq 1 ]] || die "Usage: vm-ctl token <id>"; cmd_token "$1" ;;
+  destroy) [[ $# -ge 1 ]] || die "Usage: vm-ctl destroy <id> [--force]"; cmd_destroy "$@" ;;
+  -h|--help|help) usage ;;
+  *) die "Unknown command: $cmd" ;;
+esac

package/bin/vm-setup

@@ -0,0 +1,369 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/vm-common.sh"
+CMD_NAME="${VM_SETUP_CMD_NAME:-$(basename "$0")}"
+
+usage() {
+  cat <<EOF
+Usage: $CMD_NAME --instance <id> --telegram-token <token> [options]
+
+Options:
+  --telegram-users <csv>
+  --model <id>                         (default: anthropic/claude-opus-4-6)
+  --skills <csv>                       (default: github,tmux,coding-agent,session-logs,skill-creator)
+  --openclaw-image <image>
+  --vm-vcpu <n>                        (default: 4)
+  --vm-mem-mib <n>                     (default: 8192)
+  --disk-size <size>                   (default: 40G)
+  --api-sock <path>                    (default: <fc-instance-dir>/firecracker.socket)
+  --base-kernel <path>
+  --base-rootfs <path>
+  --base-initrd <path>
+  --anthropic-api-key <key>
+  --openai-api-key <key>
+  --minimax-api-key <key>
+  --skip-browser-install
+  -h|--help
+EOF
+}
+
+INSTANCE=""
+TELEGRAM_TOKEN=""
+TELEGRAM_USERS=""
+MODEL="${MODEL:-anthropic/claude-opus-4-6}"
+SKILLS="${SKILLS:-github,tmux,coding-agent,session-logs,skill-creator}"
+OPENCLAW_IMAGE="$OPENCLAW_IMAGE_DEFAULT"
+VM_VCPU="${VM_VCPU:-4}"
+VM_MEM_MIB="${VM_MEM_MIB:-8192}"
+DISK_SIZE="${DISK_SIZE:-40G}"
+API_SOCK="${API_SOCK:-}"
+BASE_IMAGES_DIR="${BASE_IMAGES_DIR:-/srv/firecracker/base/images}"
+BASE_KERNEL="${BASE_KERNEL:-$BASE_IMAGES_DIR/vmlinux}"
+BASE_ROOTFS="${BASE_ROOTFS:-$BASE_IMAGES_DIR/rootfs.ext4}"
+BASE_INITRD="${BASE_INITRD:-$BASE_IMAGES_DIR/initrd.img}"
+SKIP_BROWSER_INSTALL="false"
+
+ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY:-}"
+OPENAI_API_KEY="${OPENAI_API_KEY:-}"
+MINIMAX_API_KEY="${MINIMAX_API_KEY:-}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --instance) INSTANCE="$2"; shift 2 ;;
+    --telegram-token) TELEGRAM_TOKEN="$2"; shift 2 ;;
+    --telegram-users) TELEGRAM_USERS="$2"; shift 2 ;;
+    --model) MODEL="$2"; shift 2 ;;
+    --skills) SKILLS="$2"; shift 2 ;;
+    --openclaw-image) OPENCLAW_IMAGE="$2"; shift 2 ;;
+    --vm-vcpu) VM_VCPU="$2"; shift 2 ;;
+    --vm-mem-mib) VM_MEM_MIB="$2"; shift 2 ;;
+    --disk-size) DISK_SIZE="$2"; shift 2 ;;
+    --api-sock) API_SOCK="$2"; shift 2 ;;
+    --base-kernel) BASE_KERNEL="$2"; shift 2 ;;
+    --base-rootfs) BASE_ROOTFS="$2"; shift 2 ;;
+    --base-initrd) BASE_INITRD="$2"; shift 2 ;;
+    --anthropic-api-key) ANTHROPIC_API_KEY="$2"; shift 2 ;;
+    --openai-api-key) OPENAI_API_KEY="$2"; shift 2 ;;
+    --minimax-api-key) MINIMAX_API_KEY="$2"; shift 2 ;;
+    --skip-browser-install) SKIP_BROWSER_INSTALL="true"; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) die "Unknown option: $1" ;;
+  esac
+done
+
+[[ -n "$INSTANCE" ]] || die "Missing --instance"
+[[ -n "$TELEGRAM_TOKEN" ]] || die "Missing --telegram-token"
+validate_instance_id "$INSTANCE"
+
+require_root
+for c in firecracker systemctl ip iptables openssl jq cloud-localds ssh scp socat curl qemu-img; do
+  require_cmd "$c"
+done
+
+[[ -f "$BASE_KERNEL" ]] || die "Kernel not found: $BASE_KERNEL"
+[[ -f "$BASE_ROOTFS" ]] || die "Rootfs not found: $BASE_ROOTFS"
+
+ensure_root_dirs
+
+if [[ ! -f "$SSH_KEY_PATH" ]]; then
+  log "Generating SSH key: $SSH_KEY_PATH"
+  mkdir -p "$(dirname "$SSH_KEY_PATH")"
+  ssh-keygen -t ed25519 -N "" -f "$SSH_KEY_PATH" >/dev/null
+fi
+
+inst_dir="$(instance_dir "$INSTANCE")"
+fc_dir="$(fc_instance_dir "$INSTANCE")"
+if [[ -z "$API_SOCK" ]]; then
+  API_SOCK="$fc_dir/firecracker.socket"
+fi
+[[ "$API_SOCK" = /* ]] || die "--api-sock must be an absolute path"
+[[ ! -e "$inst_dir" ]] || die "Instance already exists: $inst_dir"
+
+HOST_PORT="$(next_port)"
+VM_IP="$(next_ip)"
+VM_OCTET="${VM_IP##*.}"
+SHORT_ID="$(echo "$INSTANCE" | tr -cd 'a-z0-9' | cut -c1-6)"
+[[ -n "$SHORT_ID" ]] || SHORT_ID="vm"
+VM_TAP="t${SHORT_ID}${VM_OCTET}"
+VM_MAC="$(printf '06:fc:00:10:00:%02x' "$VM_OCTET")"
+GATEWAY_TOKEN="$(openssl rand -hex 32)"
+
+mkdir -p "$inst_dir/config" "$inst_dir/workspace"
+mkdir -p "$fc_dir/images" "$fc_dir/config" "$fc_dir/logs"
+mkdir -p "$(dirname "$API_SOCK")"
+
+cat > "$inst_dir/.env" <<EOF
+INSTANCE_ID=$INSTANCE
+HOST_PORT=$HOST_PORT
+VM_IP=$VM_IP
+VM_TAP=$VM_TAP
+VM_MAC=$VM_MAC
+GATEWAY_TOKEN=$GATEWAY_TOKEN
+MODEL=$MODEL
+SKILLS=$SKILLS
+TELEGRAM_USERS=$TELEGRAM_USERS
+OPENCLAW_IMAGE=$OPENCLAW_IMAGE
+VM_VCPU=$VM_VCPU
+VM_MEM_MIB=$VM_MEM_MIB
+DISK_SIZE=$DISK_SIZE
+API_SOCK=$API_SOCK
+SSH_KEY_PATH=$SSH_KEY_PATH
+SKIP_BROWSER_INSTALL=$SKIP_BROWSER_INSTALL
+ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY
+OPENAI_API_KEY=$OPENAI_API_KEY
+MINIMAX_API_KEY=$MINIMAX_API_KEY
+EOF
+
+echo "$GATEWAY_TOKEN" > "$inst_dir/.token"
+chmod 600 "$inst_dir/.token"
+
+log "Preparing VM disk and assets"
+cp --reflink=auto "$BASE_ROOTFS" "$fc_dir/images/rootfs.ext4" 2>/dev/null || cp "$BASE_ROOTFS" "$fc_dir/images/rootfs.ext4"
+if [[ -n "$DISK_SIZE" ]]; then
+  log "Resizing rootfs to $DISK_SIZE"
+  qemu-img resize "$fc_dir/images/rootfs.ext4" "$DISK_SIZE" >/dev/null
+fi
+cp "$BASE_KERNEL" "$fc_dir/images/vmlinux"
+
+INITRD_PATH=""
+if [[ -f "$BASE_INITRD" ]]; then
+  cp "$BASE_INITRD" "$fc_dir/images/initrd.img"
+  INITRD_PATH="$fc_dir/images/initrd.img"
+fi
+
+SSH_PUB_KEY="$(cat "${SSH_KEY_PATH}.pub")"
+
+cat > "$fc_dir/config/user-data" <<EOF
+#cloud-config
+users:
+  - default
+  - name: ubuntu
+    groups: [sudo, docker]
+    shell: /bin/bash
+    sudo: ALL=(ALL) NOPASSWD:ALL
+    ssh_authorized_keys:
+      - $SSH_PUB_KEY
+package_update: true
+packages:
+  - docker.io
+  - jq
+  - curl
+runcmd:
+  - [ systemctl, enable, docker ]
+  - [ systemctl, start, docker ]
+EOF
+
+cat > "$fc_dir/config/meta-data" <<EOF
+instance-id: $INSTANCE
+local-hostname: $INSTANCE
+EOF
+
+cat > "$fc_dir/config/network-config" <<EOF
+version: 2
+ethernets:
+  eth0:
+    match:
+      macaddress: "$VM_MAC"
+    set-name: eth0
+    dhcp4: false
+    addresses:
+      - $VM_IP/24
+    routes:
+      - to: 0.0.0.0/0
+        via: 172.16.0.1
+    nameservers:
+      addresses: [1.1.1.1,8.8.8.8]
+EOF
+
+cloud-localds --network-config="$fc_dir/config/network-config" "$fc_dir/images/seed.img" "$fc_dir/config/user-data" "$fc_dir/config/meta-data"
+
+jq -n \
+  --arg kernel "$fc_dir/images/vmlinux" \
+  --arg initrd "$INITRD_PATH" \
+  --arg rootfs "$fc_dir/images/rootfs.ext4" \
+  --arg seed "$fc_dir/images/seed.img" \
+  --arg tap "$VM_TAP" \
+  --arg mac "$VM_MAC" \
+  --arg log "$fc_dir/logs/firecracker.log" \
+  --argjson vcpu "$VM_VCPU" \
+  --argjson mem "$VM_MEM_MIB" '
+{
+  "boot-source": (
+    { "kernel_image_path": $kernel, "boot_args": "console=ttyS0 reboot=k panic=1 pci=off" } +
+    (if $initrd != "" then { "initrd_path": $initrd } else {} end)
+  ),
+  "drives": [
+    { "drive_id": "rootfs", "path_on_host": $rootfs, "is_root_device": true, "is_read_only": false },
+    { "drive_id": "seed", "path_on_host": $seed, "is_root_device": false, "is_read_only": true }
+  ],
+  "network-interfaces": [
+    { "iface_id": "eth0", "host_dev_name": $tap, "guest_mac": $mac }
+  ],
+  "machine-config": { "vcpu_count": $vcpu, "mem_size_mib": $mem, "smt": false },
+  "logger": { "log_path": $log, "level": "Info", "show_level": true, "show_log_origin": false }
+}
+' > "$fc_dir/config/vm-config.json"
+
+cat > "$fc_dir/start-vm.sh" <<EOF
+#!/usr/bin/env bash
+set -euo pipefail
+
+BRIDGE_NAME="$BRIDGE_NAME"
+BRIDGE_ADDR="$BRIDGE_ADDR"
+SUBNET_CIDR="$SUBNET_CIDR"
+VM_TAP="$VM_TAP"
+API_SOCK="$API_SOCK"
+CONFIG_JSON="$fc_dir/config/vm-config.json"
+
+if ! ip link show "\$BRIDGE_NAME" >/dev/null 2>&1; then
+  ip link add "\$BRIDGE_NAME" type bridge
+fi
+ip addr add "\$BRIDGE_ADDR" dev "\$BRIDGE_NAME" 2>/dev/null || true
+ip link set "\$BRIDGE_NAME" up
+sysctl -w net.ipv4.ip_forward=1 >/dev/null
+iptables -t nat -C POSTROUTING -s "\$SUBNET_CIDR" ! -o "\$BRIDGE_NAME" -j MASQUERADE 2>/dev/null || iptables -t nat -A POSTROUTING -s "\$SUBNET_CIDR" ! -o "\$BRIDGE_NAME" -j MASQUERADE
+
+ip tuntap add dev "\$VM_TAP" mode tap user root 2>/dev/null || true
+ip link set "\$VM_TAP" master "\$BRIDGE_NAME"
+ip link set "\$VM_TAP" up
+
+rm -f "\$API_SOCK"
+exec /usr/local/bin/firecracker --api-sock "\$API_SOCK" --config-file "\$CONFIG_JSON"
+EOF
+chmod +x "$fc_dir/start-vm.sh"
+
+cat > "$fc_dir/stop-vm.sh" <<EOF
+#!/usr/bin/env bash
+set -euo pipefail
+VM_TAP="$VM_TAP"
+ip link set "\$VM_TAP" down 2>/dev/null || true
+ip link del "\$VM_TAP" 2>/dev/null || true
+EOF
+chmod +x "$fc_dir/stop-vm.sh"
+
+VM_SVC="$(vm_service "$INSTANCE")"
+PROXY_SVC="$(proxy_service "$INSTANCE")"
+
+cat > "/etc/systemd/system/$VM_SVC" <<EOF
+[Unit]
+Description=Firecracker VM ($INSTANCE)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=$fc_dir/start-vm.sh
+ExecStop=$fc_dir/stop-vm.sh
+Restart=on-failure
+RestartSec=2
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+cat > "/etc/systemd/system/$PROXY_SVC" <<EOF
+[Unit]
+Description=Localhost proxy for VM ($INSTANCE)
+After=$VM_SVC
+Requires=$VM_SVC
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/socat TCP-LISTEN:$HOST_PORT,bind=127.0.0.1,reuseaddr,fork TCP:$VM_IP:18789
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+systemctl daemon-reload
+systemctl enable --now "$VM_SVC"
+
+log "Waiting for SSH on $VM_IP"
+if ! wait_for_ssh "$VM_IP" "$SSH_KEY_PATH" 180; then
+  die "VM booted but SSH was not reachable"
+fi
+
+PROVISION_VARS="$inst_dir/provision.vars"
+: > "$PROVISION_VARS"
+kv() { printf "%s=%q\n" "$1" "$2" >> "$PROVISION_VARS"; }
+
+kv INSTANCE_ID "$INSTANCE"
+kv TELEGRAM_TOKEN "$TELEGRAM_TOKEN"
+kv TELEGRAM_USERS "$TELEGRAM_USERS"
+kv MODEL "$MODEL"
+kv SKILLS "$SKILLS"
+kv GATEWAY_TOKEN "$GATEWAY_TOKEN"
+kv OPENCLAW_IMAGE "$OPENCLAW_IMAGE"
+kv SKIP_BROWSER_INSTALL "$SKIP_BROWSER_INSTALL"
+kv DISK_SIZE "$DISK_SIZE"
+kv ANTHROPIC_API_KEY "$ANTHROPIC_API_KEY"
+kv OPENAI_API_KEY "$OPENAI_API_KEY"
+kv MINIMAX_API_KEY "$MINIMAX_API_KEY"
+
+[[ -f "$REPO_ROOT/scripts/provision-guest.sh" ]] || die "Missing: $REPO_ROOT/scripts/provision-guest.sh"
+
+scp -i "$SSH_KEY_PATH" -o StrictHostKeyChecking=accept-new -o UserKnownHostsFile=/dev/null \
+  "$REPO_ROOT/scripts/provision-guest.sh" "ubuntu@$VM_IP:/tmp/provision-guest.sh"
+scp -i "$SSH_KEY_PATH" -o StrictHostKeyChecking=accept-new -o UserKnownHostsFile=/dev/null \
+  "$PROVISION_VARS" "ubuntu@$VM_IP:/tmp/provision.vars"
+
+ssh -i "$SSH_KEY_PATH" -o StrictHostKeyChecking=accept-new -o UserKnownHostsFile=/dev/null \
+  "ubuntu@$VM_IP" "sudo bash /tmp/provision-guest.sh /tmp/provision.vars"
+
+systemctl enable --now "$PROXY_SVC"
+
+host_health_ok="false"
+guest_health_ok="false"
+GUEST_HEALTH_SCRIPT="$(guest_health_script "$INSTANCE")"
+for _ in {1..30}; do
+  if [[ "$guest_health_ok" != "true" ]] && check_guest_health "$INSTANCE" "$VM_IP" "$SSH_KEY_PATH"; then
+    guest_health_ok="true"
+  fi
+  if [[ "$host_health_ok" != "true" ]] && curl -fsS "http://127.0.0.1:$HOST_PORT/health" >/dev/null 2>&1; then
+    host_health_ok="true"
+  fi
+  if [[ "$guest_health_ok" == "true" && "$host_health_ok" == "true" ]]; then
+    break
+  fi
+  sleep 2
+done
+
+echo "✓ VM instance configured"
+echo "  Instance: $INSTANCE"
+echo "  VM IP:    $VM_IP"
+echo "  Port:     $HOST_PORT"
+echo "  Token:    $GATEWAY_TOKEN"
+if [[ "$guest_health_ok" == "true" && "$host_health_ok" == "true" ]]; then
+  echo "  Health:   up (guest + proxy)"
+elif [[ "$guest_health_ok" == "true" ]]; then
+  echo "  Health:   guest up, proxy pending"
+elif [[ "$host_health_ok" == "true" ]]; then
+  echo "  Health:   proxy up (guest check pending)"
+else
+  echo "  Health:   pending (guest script: $GUEST_HEALTH_SCRIPT)"
+fi
+echo "  Status:   $(systemctl is-active "$VM_SVC") / $(systemctl is-active "$PROXY_SVC")"

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "fireclaw",
+  "version": "0.1.0",
+  "description": "Firecracker microVM control plane for isolated OpenClaw instances",
+  "bin": {
+    "fireclaw": "bin/fireclaw"
+  },
+  "files": [
+    "bin",
+    "scripts/provision-guest.sh",
+    "README.md"
+  ],
+  "scripts": {
+    "lint:shell": "bash -n bin/fireclaw && bash -n bin/vm-common.sh && bash -n bin/vm-setup && bash -n bin/vm-ctl && bash -n scripts/provision-guest.sh",
+    "test": "npm run lint:shell",
+    "pack:check": "npm pack --dry-run",
+    "prepublishOnly": "npm test && npm run pack:check"
+  },
+  "keywords": [
+    "firecracker",
+    "openclaw",
+    "vm",
+    "cli",
+    "systemd"
+  ],
+  "homepage": "https://github.com/bchewy/fireclaw#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bchewy/fireclaw.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bchewy/fireclaw/issues"
+  },
+  "license": "UNLICENSED",
+  "author": "bchewy",
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "linux"
+  ]
+}

package/scripts/provision-guest.sh

@@ -0,0 +1,334 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+[[ $# -eq 1 ]] || { echo "Usage: provision-guest.sh <vars-file>" >&2; exit 1; }
+VARS_FILE="$1"
+[[ -f "$VARS_FILE" ]] || { echo "Vars file missing: $VARS_FILE" >&2; exit 1; }
+
+set -a
+source "$VARS_FILE"
+set +a
+
+require() { [[ -n "${!1:-}" ]] || { echo "Missing required var: $1" >&2; exit 1; }; }
+
+require INSTANCE_ID
+require TELEGRAM_TOKEN
+require MODEL
+require SKILLS
+require GATEWAY_TOKEN
+require OPENCLAW_IMAGE
+
+[[ "$INSTANCE_ID" =~ ^[a-z0-9_-]+$ ]] || {
+  echo "INSTANCE_ID must match [a-z0-9_-]+" >&2
+  exit 1
+}
+
+CONFIG_ROOT="/home/ubuntu/.openclaw-${INSTANCE_ID}"
+CONFIG_DIR="$CONFIG_ROOT/config"
+WORKSPACE_DIR="/home/ubuntu/openclaw-${INSTANCE_ID}/workspace"
+TOOLS_DIR="/home/ubuntu/openclaw-${INSTANCE_ID}/tools"
+ENV_FILE="$CONFIG_ROOT/openclaw.env"
+GUEST_SERVICE="openclaw-${INSTANCE_ID}.service"
+HEALTH_SCRIPT="/usr/local/bin/openclaw-health-${INSTANCE_ID}.sh"
+
+log()  { printf '==> %s\n' "$*"; }
+warn() { printf 'Warning: %s\n' "$*" >&2; }
+
+wait_for_cloud_init() {
+  if command -v cloud-init >/dev/null 2>&1; then
+    log "Waiting for cloud-init to finish"
+    cloud-init status --wait >/dev/null 2>&1 || warn "cloud-init wait failed; continuing"
+  fi
+}
+
+wait_for_apt_locks() {
+  local timeout="${1:-300}"
+  local waited=0
+  local lock_files=(
+    /var/lib/dpkg/lock-frontend
+    /var/lib/dpkg/lock
+    /var/lib/apt/lists/lock
+    /var/cache/apt/archives/lock
+  )
+
+  while true; do
+    local locked=0
+    if command -v fuser >/dev/null 2>&1; then
+      local lock
+      for lock in "${lock_files[@]}"; do
+        if [[ -e "$lock" ]] && fuser "$lock" >/dev/null 2>&1; then
+          locked=1
+          break
+        fi
+      done
+    else
+      pgrep -f 'apt|dpkg' >/dev/null 2>&1 && locked=1
+    fi
+
+    if [[ "$locked" -eq 0 ]]; then
+      return 0
+    fi
+
+    if (( waited == 0 )); then
+      log "Waiting for apt/dpkg locks to clear"
+    fi
+    sleep 2
+    waited=$((waited + 2))
+    (( waited < timeout )) || { echo "Timed out waiting for apt locks" >&2; return 1; }
+  done
+}
+
+apt_get_retry() {
+  local attempt
+  for attempt in {1..5}; do
+    wait_for_apt_locks
+    if apt-get "$@"; then
+      return 0
+    fi
+    if (( attempt == 5 )); then
+      echo "apt-get $* failed after $attempt attempts" >&2
+      return 1
+    fi
+    warn "apt-get $* failed (attempt $attempt/5), retrying"
+    sleep 3
+  done
+}
+
+maybe_resize_rootfs() {
+  command -v resize2fs >/dev/null 2>&1 || { warn "resize2fs not found; skipping rootfs expansion"; return 0; }
+
+  local root_device fs_device fs_type
+  root_device="$(findmnt -n -o SOURCE / || true)"
+  if [[ "$root_device" == "/dev/root" ]]; then
+    root_device="$(readlink -f /dev/root || true)"
+  fi
+
+  fs_device=""
+  for candidate in "$root_device" /dev/vda; do
+    [[ -n "$candidate" && -b "$candidate" ]] || continue
+    fs_type="$(blkid -s TYPE -o value "$candidate" 2>/dev/null || true)"
+    if [[ "$fs_type" == "ext4" ]]; then
+      fs_device="$candidate"
+      break
+    fi
+  done
+
+  if [[ -z "$fs_device" ]]; then
+    warn "No ext4 root block device found for resize2fs; skipping"
+    return 0
+  fi
+
+  log "Expanding ext4 filesystem on $fs_device"
+  resize2fs "$fs_device" || warn "resize2fs failed on $fs_device; continuing"
+}
+
+ensure_docker_daemon_config() {
+  local docker_cfg="/etc/docker/daemon.json"
+  local tmp_cfg
+  local restart_needed="false"
+  tmp_cfg="$(mktemp)"
+
+  cat > "$tmp_cfg" <<'EOF'
+{
+  "iptables": false,
+  "ip6tables": false,
+  "bridge": "none"
+}
+EOF
+
+  mkdir -p /etc/docker
+  if [[ ! -f "$docker_cfg" ]] || ! cmp -s "$tmp_cfg" "$docker_cfg"; then
+    install -m 0644 "$tmp_cfg" "$docker_cfg"
+    restart_needed="true"
+  fi
+  rm -f "$tmp_cfg"
+
+  systemctl enable docker >/dev/null 2>&1 || true
+  if [[ "$restart_needed" == "true" ]]; then
+    systemctl restart docker
+  elif ! systemctl is-active --quiet docker; then
+    systemctl restart docker
+  fi
+}
+
+export DEBIAN_FRONTEND=noninteractive
+
+wait_for_cloud_init
+wait_for_apt_locks
+maybe_resize_rootfs
+
+if ! command -v docker >/dev/null 2>&1; then
+  apt_get_retry update
+  apt_get_retry install -y docker.io jq curl ca-certificates
+fi
+if ! command -v jq >/dev/null 2>&1 || ! command -v curl >/dev/null 2>&1; then
+  apt_get_retry update
+  apt_get_retry install -y jq curl ca-certificates
+fi
+ensure_docker_daemon_config
+
+mkdir -p "$CONFIG_DIR" "$WORKSPACE_DIR" "$TOOLS_DIR"
+chown -R ubuntu:ubuntu "$CONFIG_ROOT" "/home/ubuntu/openclaw-${INSTANCE_ID}"
+
+cat > "$ENV_FILE" <<EOF
+NODE_ENV=production
+BROWSER=echo
+CLAWDBOT_PREFER_PNPM=1
+OPENCLAW_PREFER_PNPM=1
+PLAYWRIGHT_BROWSERS_PATH=/home/node/clawd/tools/.playwright
+OPENCLAW_GATEWAY_TOKEN=$GATEWAY_TOKEN
+ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
+OPENAI_API_KEY=${OPENAI_API_KEY:-}
+MINIMAX_API_KEY=${MINIMAX_API_KEY:-}
+EOF
+chmod 600 "$ENV_FILE"
+
+docker pull "$OPENCLAW_IMAGE"
+
+run_openclaw_cli() {
+  docker run --rm -i -T \
+    --network host \
+    -e HOME=/home/node \
+    -e OPENCLAW_GATEWAY_TOKEN="$GATEWAY_TOKEN" \
+    -e OPENCLAW_TELEGRAM_TOKEN="$TELEGRAM_TOKEN" \
+    -e OPENCLAW_MODEL="$MODEL" \
+    -e OPENCLAW_TELEGRAM_ALLOW_FROM_JSON="$telegram_allow_from_json" \
+    -e OPENCLAW_SKILLS_JSON="$skills_json" \
+    -e OPENCLAW_BROWSER_PATH="${OPENCLAW_BROWSER_PATH:-}" \
+    -e OPENCLAW_MINIMAX_PROVIDER_JSON="${OPENCLAW_MINIMAX_PROVIDER_JSON:-}" \
+    -e ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY:-}" \
+    -e OPENAI_API_KEY="${OPENAI_API_KEY:-}" \
+    -e MINIMAX_API_KEY="${MINIMAX_API_KEY:-}" \
+    -v "$CONFIG_DIR:/home/node/.openclaw" \
+    -v "$WORKSPACE_DIR:/home/node/.openclaw/workspace" \
+    -v "$TOOLS_DIR:/home/node/clawd/tools" \
+    --entrypoint /bin/bash \
+    "$OPENCLAW_IMAGE" -se
+}
+
+skills_json="[]"
+IFS=',' read -r -a skills_arr <<< "${SKILLS:-}"
+if (( ${#skills_arr[@]} > 0 )); then
+  skills_json="$(printf '%s\n' "${skills_arr[@]}" | sed '/^$/d' | jq -R . | jq -s .)"
+fi
+
+telegram_allow_from_json="[]"
+IFS=',' read -r -a users_arr <<< "${TELEGRAM_USERS:-}"
+if (( ${#users_arr[@]} > 0 )); then
+  telegram_allow_from_json="$(printf '%s\n' "${users_arr[@]}" | sed '/^$/d' | jq -R . | jq -s .)"
+fi
+
+run_openclaw_cli <<'EOF'
+set -euo pipefail
+OPENCLAW='node /app/openclaw.mjs'
+$OPENCLAW config set gateway.mode local
+$OPENCLAW config set gateway.bind lan
+$OPENCLAW config set gateway.auth.mode token
+$OPENCLAW config set gateway.auth.token "$OPENCLAW_GATEWAY_TOKEN"
+$OPENCLAW config set gateway.tailscale.mode off
+$OPENCLAW config set agents.defaults.model.primary "$OPENCLAW_MODEL"
+$OPENCLAW config set agents.defaults.skipBootstrap false --json
+$OPENCLAW config set channels.telegram.enabled true --json
+$OPENCLAW config set channels.telegram.botToken "$OPENCLAW_TELEGRAM_TOKEN"
+$OPENCLAW config set channels.telegram.dmPolicy allowlist
+$OPENCLAW config set channels.telegram.groupPolicy disabled
+$OPENCLAW config set channels.telegram.allowFrom "$OPENCLAW_TELEGRAM_ALLOW_FROM_JSON" --json
+$OPENCLAW config set plugins.entries.telegram.enabled true --json
+$OPENCLAW config set skills.allowBundled "$OPENCLAW_SKILLS_JSON" --json
+EOF
+
+if [[ "$MODEL" == minimax/* ]]; then
+  OPENCLAW_MINIMAX_PROVIDER_JSON="$(jq -cn --arg api_key "${MINIMAX_API_KEY:-}" '
+    {
+      baseUrl: "https://api.minimax.io/anthropic",
+      apiKey: $api_key,
+      api: "anthropic-messages",
+      models: [
+        {
+          id: "MiniMax-M2.1",
+          name: "MiniMax M2.1",
+          reasoning: false,
+          input: ["text"],
+          contextWindow: 200000,
+          maxTokens: 8192
+        }
+      ]
+    }
+  ')"
+  run_openclaw_cli <<'EOF'
+OPENCLAW='node /app/openclaw.mjs'
+$OPENCLAW config set models.mode merge
+$OPENCLAW config set models.providers.minimax "$OPENCLAW_MINIMAX_PROVIDER_JSON" --json
+EOF
+fi
+
+if [[ "${SKIP_BROWSER_INSTALL:-false}" != "true" ]]; then
+  docker run --rm -T \
+    --network host \
+    -e PLAYWRIGHT_BROWSERS_PATH=/home/node/clawd/tools/.playwright \
+    -v "$TOOLS_DIR:/home/node/clawd/tools" \
+    --entrypoint /bin/bash \
+    "$OPENCLAW_IMAGE" -lc "
+      set -euo pipefail
+      npx --yes playwright@latest install chromium
+    "
+
+  chrome_host_path="$(
+    find "$TOOLS_DIR/.playwright" -type f \
+      \( -path '*/chromium_headless_shell-*/chrome-headless-shell' -o -name 'chrome-headless-shell' -o -name 'headless_shell' \) \
+      | sort | head -n 1 || true
+  )"
+  if [[ -n "$chrome_host_path" ]]; then
+    chrome_container_path="${chrome_host_path/#$TOOLS_DIR/\/home\/node\/clawd\/tools}"
+    OPENCLAW_BROWSER_PATH="$chrome_container_path"
+    run_openclaw_cli <<'EOF'
+OPENCLAW='node /app/openclaw.mjs'
+$OPENCLAW config set browser.executablePath "$OPENCLAW_BROWSER_PATH"
+EOF
+  else
+    warn "Playwright Chromium installed but executable path was not found in $TOOLS_DIR/.playwright"
+  fi
+fi
+
+run_openclaw_cli <<'EOF'
+set -euo pipefail
+OPENCLAW='node /app/openclaw.mjs'
+$OPENCLAW doctor --fix || true
+EOF
+
+cat > "$HEALTH_SCRIPT" <<EOF
+#!/usr/bin/env bash
+set -euo pipefail
+
+CONTAINER_NAME="openclaw-${INSTANCE_ID}"
+
+if ! /usr/bin/docker inspect -f '{{.State.Running}}' "\$CONTAINER_NAME" 2>/dev/null | grep -qx true; then
+  exit 1
+fi
+
+curl -fsS http://127.0.0.1:18789/health >/dev/null
+EOF
+chmod 755 "$HEALTH_SCRIPT"
+
+cat > "/etc/systemd/system/$GUEST_SERVICE" <<EOF
+[Unit]
+Description=OpenClaw ($INSTANCE_ID)
+After=docker.service network-online.target
+Requires=docker.service
+
+[Service]
+Type=simple
+ExecStartPre=-/usr/bin/docker rm -f openclaw-$INSTANCE_ID
+ExecStart=/usr/bin/docker run --rm --name openclaw-$INSTANCE_ID --init --network host --env-file $ENV_FILE -v $CONFIG_DIR:/home/node/.openclaw -v $WORKSPACE_DIR:/home/node/.openclaw/workspace -v $TOOLS_DIR:/home/node/clawd/tools $OPENCLAW_IMAGE node dist/index.js gateway --bind lan --port 18789
+ExecStop=/usr/bin/docker stop openclaw-$INSTANCE_ID
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+systemctl daemon-reload
+systemctl enable --now "$GUEST_SERVICE"
+
+echo "Guest provisioning complete for $INSTANCE_ID"