fireclaw 0.1.1 → 0.1.2

package/README.md

@@ -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
@@ -129,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
 
@@ -140,7 +140,7 @@ All scripts respect these overrides:
 | `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

@@ -4,30 +4,32 @@ set -euo pipefail
 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 fireclaw setup --instance my-bot --telegram-token <token> --telegram-users <uid>
-  sudo fireclaw list
-  sudo 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

@@ -6,12 +6,12 @@ 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

@@ -29,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
@@ -53,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() {
@@ -67,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
@@ -83,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() {

package/package.json

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