fireclaw 0.1.0 → 0.1.2

package/README.md

@@ -1,4 +1,4 @@
-# fireclaw-vm-demo
+# fireclaw
 
 Run [OpenClaw](https://github.com/openclaw/openclaw) instances inside Firecracker microVMs, each fully isolated with its own filesystem, network, and process tree.
 
@@ -19,7 +19,7 @@ This repo is a minimal control plane that wires up Firecracker VM lifecycle, net
 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
+├── bridge: fc-br0 (172.16.0.0/24)              ← shared bridge for all VMs
 │
 └── Firecracker VM (172.16.0.x)
     ├── cloud-init: ubuntu user, SSH key, Docker install
@@ -32,11 +32,11 @@ Host
 
 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.
+3. **`fireclaw`** manages the 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
+- **Instance state** `/var/lib/fireclaw/.vm-<id>/` — env file, token, provision vars
+- **VM runtime** `/srv/firecracker/vm-demo/<id>/` — VM images, Firecracker config, logs
 
 ## Prerequisites
 
@@ -48,17 +48,15 @@ All state lives in two places:
 
 Set `BASE_IMAGES_DIR` or pass `--base-kernel`/`--base-rootfs`/`--base-initrd` to point at your images.
 
-## Setup
+## Install
 
 ```bash
-# 1. Clone
-git clone https://github.com/bchewy/fireclaw-vm-demo.git
-cd fireclaw-vm-demo
+npm install -g fireclaw
+```
 
-# 2. (Optional) install global CLI
-sudo install -m 0755 ./bin/fireclaw /usr/local/bin/fireclaw
+## Setup
 
-# 3. Create an instance
+```bash
 sudo fireclaw setup \
   --instance my-bot \
   --telegram-token "<your-bot-token>" \
@@ -67,34 +65,7 @@ sudo fireclaw setup \
   --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.
+This will generate an SSH keypair (if needed), copy + configure the rootfs, boot the VM via systemd, wait for SSH, provision OpenClaw inside the guest, start the localhost proxy, and print the instance details (IP, port, token).
 
 ### Options
 
@@ -158,7 +129,7 @@ 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.
+Each VM gets a static IP on a bridge (`fc-br0`, `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
 
@@ -166,10 +137,10 @@ All scripts respect these overrides:
 
 | Variable | Default |
 |----------|---------|
-| `STATE_ROOT` | `<repo>/.vm-demo` |
+| `STATE_ROOT` | `/var/lib/fireclaw` |
 | `FC_ROOT` | `/srv/firecracker/vm-demo` |
 | `BASE_PORT` | `18890` |
-| `BRIDGE_NAME` | `fcbr0` |
+| `BRIDGE_NAME` | `fc-br0` |
 | `BRIDGE_ADDR` | `172.16.0.1/24` |
 | `SUBNET_CIDR` | `172.16.0.0/24` |
 | `SSH_KEY_PATH` | `~/.ssh/vmdemo_vm` |

package/bin/fireclaw

@@ -1,33 +1,35 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "$0")")" && pwd)"
 
 usage() {
-  cat <<'EOF'
-Usage: fireclaw <command> [args...]
+  local bold=$'\033[1m' dim=$'\033[2m' reset=$'\033[0m' cyan=$'\033[36m'
 
-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
+  cat <<EOF
+${bold}fireclaw${reset} — Firecracker microVM control plane
 
-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
+${bold}USAGE${reset}
+  fireclaw <command> [args...]
 
-Examples:
-  sudo ./bin/fireclaw setup --instance my-bot --telegram-token <token> --telegram-users <uid>
-  sudo ./bin/fireclaw list
-  sudo ./bin/fireclaw status my-bot
+${bold}COMMANDS${reset}
+  ${cyan}setup${reset} <flags...>             Create and provision a new VM instance
+  ${cyan}list${reset}                         List all instances
+  ${cyan}status${reset} [id]                  Show instance status (all or one)
+  ${cyan}start${reset} <id>                   Start an instance
+  ${cyan}stop${reset} <id>                    Stop an instance
+  ${cyan}restart${reset} <id>                 Restart an instance
+  ${cyan}logs${reset} <id> [guest|host]       Stream logs
+  ${cyan}shell${reset} <id> [command...]      SSH into VM or run a command
+  ${cyan}token${reset} <id>                   Print gateway token
+  ${cyan}destroy${reset} <id> [--force]       Destroy an instance
+
+${bold}EXAMPLES${reset}
+  ${dim}\$${reset} sudo fireclaw setup --instance my-bot --telegram-token <tok> --telegram-users <uid>
+  ${dim}\$${reset} sudo fireclaw list
+  ${dim}\$${reset} sudo fireclaw status my-bot
+  ${dim}\$${reset} sudo fireclaw shell my-bot
+  ${dim}\$${reset} sudo fireclaw logs my-bot guest
 EOF
 }
 

package/bin/vm-common.sh

@@ -1,17 +1,17 @@
 #!/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}"
+REPO_ROOT="${REPO_ROOT:-$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/.." && pwd)}"
 FC_ROOT="${FC_ROOT:-/srv/firecracker/vm-demo}"
+STATE_ROOT="${STATE_ROOT:-/var/lib/fireclaw}"
 BASE_PORT="${BASE_PORT:-18890}"
 
-BRIDGE_NAME="${BRIDGE_NAME:-fcbr0}"
+BRIDGE_NAME="${BRIDGE_NAME:-fc-br0}"
 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}"
+SSH_KEY_PATH="${SSH_KEY_PATH:-/home/ubuntu/.ssh/vmdemo_vm}"
 
 log()  { printf '==> %s\n' "$*"; }
 warn() { printf 'Warning: %s\n' "$*" >&2; }
@@ -96,14 +96,30 @@ wait_for_ssh() {
   local ip="$1"
   local key="${2:-$SSH_KEY_PATH}"
   local retries="${3:-120}"
+
+  if [[ ! -r "$key" ]]; then
+    if [[ $EUID -ne 0 ]]; then
+      die "Cannot read SSH key: $key (try: sudo fireclaw ...)"
+    else
+      die "SSH key not found: $key"
+    fi
+  fi
+
+  local vm_svc vm_state
+  vm_svc="$(vm_service "${INSTANCE_ID:-}")"
+
   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
+    vm_state="$(systemctl is-active "$vm_svc" 2>/dev/null)" || vm_state="inactive"
+    if [[ "$vm_state" != "active" ]]; then
+      die "VM is not running ($(printf '\033[31m%s\033[0m' "$vm_state")). Start it with: sudo fireclaw start ${INSTANCE_ID:-<id>}"
+    fi
     sleep 2
   done
-  return 1
+  die "VM is running but SSH did not become reachable at ubuntu@$ip after $((retries * 2))s"
 }
 
 check_guest_health() {

package/bin/vm-ctl

@@ -1,9 +1,10 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "$0")")" && pwd)"
 source "$SCRIPT_DIR/vm-common.sh"
-CMD_NAME="${VM_CTL_CMD_NAME:-$(basename "$0")}"
+
+CMD_NAME="${VM_CTL_CMD_NAME:-fireclaw}"
 
 usage() {
   cat <<EOF
@@ -28,11 +29,45 @@ ssh_run() {
   ssh -i "$key" -o StrictHostKeyChecking=accept-new -o UserKnownHostsFile=/dev/null "ubuntu@$ip" "$@"
 }
 
+_color() {
+  local val="$1"
+  local green=$'\033[32m' red=$'\033[31m' yellow=$'\033[33m' reset=$'\033[0m'
+  case "$val" in
+    active|up)       printf '%s%s%s' "$green"  "$val" "$reset" ;;
+    inactive|down)   printf '%s%s%s' "$red"    "$val" "$reset" ;;
+    failed)          printf '%s%s%s' "$red"    "$val" "$reset" ;;
+    *)               printf '%s%s%s' "$yellow" "$val" "$reset" ;;
+  esac
+}
+
+_print_status_table() {
+  local -a ids=() ips=() ports=() vms=() proxies=() healths=()
+  local id ip port vm proxy health
+
+  while IFS='|' read -r id ip port vm proxy health; do
+    ids+=("$id"); ips+=("$ip"); ports+=("$port")
+    vms+=("$vm"); proxies+=("$proxy"); healths+=("$health")
+  done
+
+  [[ ${#ids[@]} -gt 0 ]] || { echo "(no instances)"; return; }
+
+  local hdr=$'\033[1;37m' reset=$'\033[0m' dim=$'\033[2m'
+  printf "${hdr}%-14s %-14s %-7s %-10s %-10s %-8s${reset}\n" \
+    "INSTANCE" "IP" "PORT" "VM" "PROXY" "HEALTH"
+  printf "${dim}%-14s %-14s %-7s %-10s %-10s %-8s${reset}\n" \
+    "--------" "----------" "-----" "------" "-------" "------"
+
+  for i in "${!ids[@]}"; do
+    printf "%-14s %-14s %-7s %-10b %-10b %-8b\n" \
+      "${ids[$i]}" "${ips[$i]}" "${ports[$i]}" \
+      "$(_color "${vms[$i]}")" "$(_color "${proxies[$i]}")" "$(_color "${healths[$i]}")"
+  done
+}
+
 cmd_list() {
   shopt -s nullglob
-  local found="false"
+  local rows=()
   for d in "$STATE_ROOT"/.vm-*/; do
-    found="true"
     local id
     id="$(basename "$d" | sed 's/^\.vm-//')"
     if [[ ! "$id" =~ ^[a-z0-9_-]+$ ]]; then
@@ -52,12 +87,12 @@ cmd_list() {
       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"
+    vm_state="$(systemctl is-active "$(vm_service "$id")" 2>/dev/null)" || vm_state="inactive"
+    proxy_state="$(systemctl is-active "$(proxy_service "$id")" 2>/dev/null)" || proxy_state="inactive"
+    rows+=("${id}|${VM_IP}|${HOST_PORT}|${vm_state}|${proxy_state}|${health}")
   done
   shopt -u nullglob
-  [[ "$found" == "true" ]] || echo "(no instances)"
+  printf '%s\n' "${rows[@]}" | _print_status_table
 }
 
 cmd_status_one() {
@@ -66,15 +101,15 @@ cmd_status_one() {
   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)"
+  vm_state="$(systemctl is-active "$(vm_service "$id")" 2>/dev/null)" || vm_state="inactive"
+  proxy_state="$(systemctl is-active "$(proxy_service "$id")" 2>/dev/null)" || proxy_state="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)"
+    guest="$(ssh_run "$VM_IP" "systemctl is-active openclaw-$id.service" 2>/dev/null)" || guest="unknown"
     if check_guest_health "$id" "$VM_IP" "$ssh_key"; then
       guest_health="up"
     fi
@@ -82,7 +117,17 @@ cmd_status_one() {
   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"
+
+  local bold=$'\033[1m' dim=$'\033[2m' reset=$'\033[0m'
+  printf "${bold}%s${reset}\n" "$id"
+  printf "  %-16s %s\n" "IP" "$VM_IP"
+  printf "  %-16s %s\n" "Proxy port" "$HOST_PORT"
+  printf "  %-16s %b\n" "VM" "$(_color "$vm_state")"
+  printf "  %-16s %b\n" "Proxy" "$(_color "$proxy_state")"
+  printf "  %-16s %b\n" "Guest service" "$(_color "$guest")"
+  printf "  %-16s %b\n" "Health" "$(_color "$health")"
+  printf "  %-16s %b\n" "  Host health" "$(_color "$host_health")"
+  printf "  %-16s %b\n" "  Guest health" "$(_color "$guest_health")"
 }
 
 cmd_status() {
@@ -196,13 +241,13 @@ 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 "$@" ;;
+  start) [[ $# -eq 1 ]] || die "Usage: $CMD_NAME start <id>"; cmd_start "$1" ;;
+  stop) [[ $# -eq 1 ]] || die "Usage: $CMD_NAME stop <id>"; cmd_stop "$1" ;;
+  restart) [[ $# -eq 1 ]] || die "Usage: $CMD_NAME restart <id>"; cmd_restart "$1" ;;
+  logs) [[ $# -ge 1 ]] || die "Usage: $CMD_NAME logs <id> [guest|host]"; cmd_logs "$@" ;;
+  shell) [[ $# -ge 1 ]] || die "Usage: $CMD_NAME shell <id> [command...]"; id="$1"; shift; cmd_shell "$id" "$@" ;;
+  token) [[ $# -eq 1 ]] || die "Usage: $CMD_NAME token <id>"; cmd_token "$1" ;;
+  destroy) [[ $# -ge 1 ]] || die "Usage: $CMD_NAME destroy <id> [--force]"; cmd_destroy "$@" ;;
   -h|--help|help) usage ;;
   *) die "Unknown command: $cmd" ;;
 esac

package/bin/vm-provision

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "$0")")" && pwd)"
+source "$SCRIPT_DIR/vm-common.sh"
+
+usage() {
+  cat <<EOF
+Usage: fireclaw provision <instance>
+EOF
+}
+
+[[ $# -eq 1 ]] || { usage; exit 1; }
+
+INSTANCE="$1"
+validate_instance_id "$INSTANCE"
+require_root
+
+load_instance_env "$INSTANCE"
+
+PROVISION_VARS="$(instance_dir "$INSTANCE")/provision.vars"
+[[ -f "$PROVISION_VARS" ]] || die "Missing provision vars: $PROVISION_VARS"
+[[ -f "$REPO_ROOT/scripts/provision-guest.sh" ]] || die "Missing: $REPO_ROOT/scripts/provision-guest.sh"
+
+if ! wait_for_ssh "$VM_IP" "$SSH_KEY_PATH" 180; then
+  die "VM SSH unreachable. Start it first: fireclaw start $INSTANCE"
+fi
+
+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_service "$INSTANCE")" >/dev/null 2>&1 || true
+
+health_ok="false"
+for _ in {1..30}; do
+  if curl -fsS "http://127.0.0.1:$HOST_PORT/health" >/dev/null 2>&1; then
+    health_ok="true"
+    break
+  fi
+  sleep 2
+done
+
+echo "✓ VM provisioning complete"
+echo "  Instance: $INSTANCE"
+echo "  VM IP:    $VM_IP"
+echo "  Port:     $HOST_PORT"
+if [[ "$health_ok" != "true" ]]; then
+  echo "  Health:   pending (service may still be warming up)"
+fi

package/bin/vm-setup

@@ -1,9 +1,10 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "$0")")" && pwd)"
 source "$SCRIPT_DIR/vm-common.sh"
-CMD_NAME="${VM_SETUP_CMD_NAME:-$(basename "$0")}"
+
+CMD_NAME="${VM_SETUP_CMD_NAME:-fireclaw setup}"
 
 usage() {
   cat <<EOF
@@ -158,11 +159,11 @@ 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
+    lock_passwd: true
     ssh_authorized_keys:
       - $SSH_PUB_KEY
 package_update: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fireclaw",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Firecracker microVM control plane for isolated OpenClaw instances",
   "bin": {
     "fireclaw": "bin/fireclaw"

package/scripts/provision-guest.sh

@@ -186,7 +186,7 @@ chmod 600 "$ENV_FILE"
 docker pull "$OPENCLAW_IMAGE"
 
 run_openclaw_cli() {
-  docker run --rm -i -T \
+  docker run --rm -i \
     --network host \
     -e HOME=/home/node \
     -e OPENCLAW_GATEWAY_TOKEN="$GATEWAY_TOKEN" \
@@ -263,7 +263,7 @@ EOF
 fi
 
 if [[ "${SKIP_BROWSER_INSTALL:-false}" != "true" ]]; then
-  docker run --rm -T \
+  docker run --rm \
     --network host \
     -e PLAYWRIGHT_BROWSERS_PATH=/home/node/clawd/tools/.playwright \
     -v "$TOOLS_DIR:/home/node/clawd/tools" \