fireclaw 0.1.1 → 0.2.0

package/bin/vm-ctl

@@ -11,6 +11,7 @@ usage() {
 Usage: $CMD_NAME <command> [instance]
 
 Commands:
+  doctor
   list
   status [id]
   start <id>
@@ -24,58 +25,119 @@ EOF
 }
 
 ssh_run() {
+  local id="$1"; shift
   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" "$@"
+  ssh -i "$key" -o StrictHostKeyChecking=accept-new -o UserKnownHostsFile="$(ssh_known_hosts_file "$id")" "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
+}
+
+# printf pads by byte count, so colorize after padding to keep columns aligned.
+_color_cell() {
+  local width="$1"
+  local val="$2"
+  local pad=$(( width - ${#val} ))
+  (( pad > 0 )) || pad=0
+  printf '%b%*s' "$(_color "$val")" "$pad" ""
+}
+
+_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 %s %s %s\n" \
+      "${ids[$i]}" "${ips[$i]}" "${ports[$i]}" \
+      "$(_color_cell 10 "${vms[$i]}")" "$(_color_cell 10 "${proxies[$i]}")" "$(_color_cell 8 "${healths[$i]}")"
+  done
 }
 
 cmd_list() {
+  require_root
+  local nullglob_was_set=0
+  shopt -q nullglob && nullglob_was_set=1
   shopt -s nullglob
-  local found="false"
+  local rows=()
   for d in "$STATE_ROOT"/.vm-*/; do
-    found="true"
-    local id
+    local id row
     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"
+    # Subshell so one corrupt .env degrades to an error row instead of
+    # killing the whole fleet view, and loaded values cannot leak across
+    # instances.
+    if row="$(
+      load_instance_env "$id" >/dev/null 2>&1 || exit 1
+      ssh_key="${SSH_KEY_PATH:-$HOME/.ssh/vmdemo_vm}"
+      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"
+      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
+      vm_state="$(systemctl is-active "$(vm_service "$id")" 2>/dev/null || true)"
+      proxy_state="$(systemctl is-active "$(proxy_service "$id")" 2>/dev/null || true)"
+      printf '%s|%s|%s|%s|%s|%s' "$id" "$VM_IP" "$HOST_PORT" "${vm_state:-inactive}" "${proxy_state:-inactive}" "$health"
+    )"; then
+      rows+=("$row")
+    else
+      warn "Unreadable instance state for '$id' (inspect: $d.env)"
+      rows+=("${id}|?|?|error|error|down")
     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)"
+  (( nullglob_was_set )) || shopt -u nullglob
+  if (( ${#rows[@]} == 0 )); then
+    _print_status_table < /dev/null
+  else
+    printf '%s\n' "${rows[@]}" | _print_status_table
+  fi
 }
 
 cmd_status_one() {
   local id="$1"
   validate_instance_id "$id"
+  require_root
   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)"
+  if ssh_reachable "$VM_IP" "$ssh_key" "$id"; then
+    guest="$(ssh_run "$id" "$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 +145,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() {
@@ -101,11 +173,16 @@ cmd_start() {
   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"
+  wait_for_ssh "$VM_IP" "$SSH_KEY_PATH" 180 "$id" || die "VM started but SSH unreachable"
 
-  ssh_run "$VM_IP" "sudo systemctl enable --now openclaw-$id.service" || warn "Guest service start failed"
+  ssh_run "$id" "$VM_IP" "sudo systemctl enable --now openclaw-$id.service" || warn "Guest service start failed"
   systemctl enable --now "$(proxy_service "$id")"
 
+  if ! wait_for_instance_health "$id" "$VM_IP" "$HOST_PORT" "$SSH_KEY_PATH" 30; then
+    cmd_status_one "$id"
+    die "Health checks did not pass for $id after start"
+  fi
+
   cmd_status_one "$id"
 }
 
@@ -116,10 +193,15 @@ cmd_stop() {
   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
+  if ssh_reachable "$VM_IP" "$SSH_KEY_PATH" "$id"; then
+    ssh_run "$id" "$VM_IP" "sudo systemctl stop openclaw-$id.service" || true
+  else
+    warn "VM SSH unavailable; skipping guest service stop"
   fi
-  systemctl stop "$(vm_service "$id")"
+  systemctl stop "$(vm_service "$id")" || warn "Failed to stop $(vm_service "$id")"
+  # Without disabling, a stopped instance silently resurrects on host reboot.
+  systemctl disable "$(proxy_service "$id")" 2>/dev/null || true
+  systemctl disable "$(vm_service "$id")" 2>/dev/null || true
   cmd_status_one "$id"
 }
 
@@ -132,43 +214,59 @@ cmd_logs() {
   local id="$1"
   local mode="${2:-guest}"
   validate_instance_id "$id"
+  require_root
   load_instance_env "$id"
+  [[ "$mode" == "guest" || "$mode" == "host" ]] || die "Usage: $CMD_NAME logs <id> [guest|host]"
 
   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"
+  wait_for_ssh "$VM_IP" "$SSH_KEY_PATH" 30 "$id" || die "VM SSH unavailable"
+  ssh_run "$id" "$VM_IP" "sudo journalctl -u openclaw-$id.service -f"
 }
 
 cmd_shell() {
   local id="$1"
   shift || true
   validate_instance_id "$id"
+  require_root
   load_instance_env "$id"
-  wait_for_ssh "$VM_IP" "$SSH_KEY_PATH" 30 || die "VM SSH unavailable"
+  wait_for_ssh "$VM_IP" "$SSH_KEY_PATH" 30 "$id" || die "VM SSH unavailable"
 
   if [[ $# -gt 0 ]]; then
-    ssh_run "$VM_IP" "$*"
+    ssh_run "$id" "$VM_IP" "$*"
   else
-    ssh -i "$SSH_KEY_PATH" -o StrictHostKeyChecking=accept-new -o UserKnownHostsFile=/dev/null "ubuntu@$VM_IP"
+    ssh -i "$SSH_KEY_PATH" -o StrictHostKeyChecking=accept-new -o UserKnownHostsFile="$(ssh_known_hosts_file "$id")" "ubuntu@$VM_IP"
   fi
 }
 
 cmd_token() {
   local id="$1"
   validate_instance_id "$id"
+  require_root
   cat "$(instance_token "$id")"
 }
 
 cmd_destroy() {
+  [[ $# -eq 1 || ( $# -eq 2 && "$2" == "--force" ) ]] || die "Usage: $CMD_NAME destroy <id> [--force]"
   local id="$1"
   local force="${2:-}"
   validate_instance_id "$id"
   require_root
-  load_instance_env "$id"
+
+  local env_ok="true"
+  if ! (load_instance_env "$id") >/dev/null 2>&1; then
+    env_ok="false"
+    if [[ "$force" != "--force" ]]; then
+      die "Cannot read state for '$id'; use --force to remove its units and directories anyway"
+    fi
+    warn "State for '$id' is unreadable; best-effort cleanup of units and directories"
+  fi
+  if [[ "$env_ok" == "true" ]]; then
+    load_instance_env "$id"
+  fi
 
   if [[ "$force" != "--force" ]]; then
     read -r -p "Destroy '$id' and remove VM assets? [y/N] " confirm
@@ -183,27 +281,118 @@ cmd_destroy() {
   rm -f "/etc/systemd/system/$(proxy_service "$id")"
   rm -f "/etc/systemd/system/$(vm_service "$id")"
   systemctl daemon-reload
+  systemctl reset-failed "$(proxy_service "$id")" "$(vm_service "$id")" 2>/dev/null || true
+
+  if [[ "$env_ok" == "true" ]]; then
+    if [[ -n "${VM_TAP:-}" ]]; then
+      ip link set "$VM_TAP" down 2>/dev/null || true
+      ip link del "$VM_TAP" 2>/dev/null || true
+    fi
+    if [[ -n "${API_SOCK:-}" ]]; then
+      rm -f "$API_SOCK"
+    fi
+  fi
 
   rm -rf "$(instance_dir "$id")" "$(fc_instance_dir "$id")"
 
   echo "Destroyed: $id"
 }
 
+cmd_doctor() {
+  local failures=0
+
+  _check() {
+    local label="$1"
+    local ok="$2"
+    local detail="${3:-}"
+    local green=$'\033[32m' red=$'\033[31m' yellow=$'\033[33m' reset=$'\033[0m'
+    if [[ "$ok" == "pass" ]]; then
+      printf '%s✓%s %s%s\n' "$green" "$reset" "$label" "${detail:+ ($detail)}"
+    elif [[ "$ok" == "skip" ]]; then
+      printf '%s-%s %s%s\n' "$yellow" "$reset" "$label" "${detail:+ ($detail)}"
+    else
+      printf '%s✗%s %s%s\n' "$red" "$reset" "$label" "${detail:+ ($detail)}"
+      failures=$((failures + 1))
+    fi
+  }
+
+  local c
+  for c in firecracker systemctl ip bridge iptables openssl jq cloud-localds ssh scp socat curl qemu-img install flock; do
+    if command -v "$c" >/dev/null 2>&1; then
+      _check "command: $c" pass
+    else
+      _check "command: $c" fail "not found on PATH"
+    fi
+  done
+
+  if [[ -e /dev/kvm ]]; then
+    if [[ -r /dev/kvm && -w /dev/kvm ]]; then
+      _check "/dev/kvm" pass
+    else
+      _check "/dev/kvm" fail "exists but not accessible by $(id -un)"
+    fi
+  else
+    _check "/dev/kvm" fail "missing (KVM required)"
+  fi
+
+  local img
+  for img in "${BASE_KERNEL:-${BASE_IMAGES_DIR:-/srv/firecracker/base/images}/vmlinux}" "${BASE_ROOTFS:-${BASE_IMAGES_DIR:-/srv/firecracker/base/images}/rootfs.ext4}"; do
+    if [[ -f "$img" ]]; then
+      _check "base image: $img" pass
+    else
+      _check "base image: $img" fail "missing"
+    fi
+  done
+
+  if ip link show "$BRIDGE_NAME" >/dev/null 2>&1; then
+    _check "bridge: $BRIDGE_NAME" pass "$(ip -4 -o addr show dev "$BRIDGE_NAME" | awk '{print $4}' | head -1)"
+  else
+    _check "bridge: $BRIDGE_NAME" skip "absent (setup creates it)"
+  fi
+
+  if [[ $EUID -eq 0 ]]; then
+    if iptables -t nat -C POSTROUTING -s "$SUBNET_CIDR" ! -o "$BRIDGE_NAME" -j MASQUERADE >/dev/null 2>&1; then
+      _check "NAT rule for $SUBNET_CIDR" pass
+    else
+      _check "NAT rule for $SUBNET_CIDR" skip "absent (setup adds it)"
+    fi
+    if [[ -d "$STATE_ROOT" && -w "$STATE_ROOT" ]]; then
+      _check "state root: $STATE_ROOT" pass
+    else
+      _check "state root: $STATE_ROOT" skip "absent (setup creates it)"
+    fi
+  else
+    _check "NAT rule / state root" skip "requires root"
+  fi
+
+  local mem_avail_mib disk_avail
+  mem_avail_mib="$(awk '/^MemAvailable:/ {print int($2/1024)}' /proc/meminfo 2>/dev/null || echo "?")"
+  disk_avail="$(df -h --output=avail "$FC_ROOT" 2>/dev/null | tail -1 | tr -d ' ' || echo "?")"
+  _check "capacity" pass "MemAvailable: ${mem_avail_mib} MiB, free on $FC_ROOT: ${disk_avail:-?}"
+
+  echo
+  if (( failures > 0 )); then
+    die "$failures check(s) failed"
+  fi
+  echo "All checks passed"
+}
+
 [[ $# -ge 1 ]] || { usage; exit 1; }
 
 cmd="$1"
 shift || true
 
 case "$cmd" in
+  doctor) [[ $# -eq 0 ]] || die "Usage: $CMD_NAME doctor"; cmd_doctor ;;
   list) cmd_list ;;
-  status) cmd_status "$@" ;;
+  status) [[ $# -le 1 ]] || die "Usage: $CMD_NAME status [id]"; cmd_status "$@" ;;
   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 "$@" ;;
+  logs) [[ $# -ge 1 && $# -le 2 ]] || 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 "$@" ;;
+  destroy) cmd_destroy "$@" ;;
   -h|--help|help) usage ;;
   *) die "Unknown command: $cmd" ;;
 esac

package/bin/vm-provision

@@ -4,51 +4,185 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "$0")")" && pwd)"
 source "$SCRIPT_DIR/vm-common.sh"
 
+CMD_NAME="${VM_PROVISION_CMD_NAME:-fireclaw provision}"
+
 usage() {
   cat <<EOF
-Usage: fireclaw provision <instance>
+Usage: $CMD_NAME <instance> [options]
+
+Each option updates the saved instance config, then guest provisioning reruns
+with the result. With no options, provisioning reruns with the saved config.
+
+Options:
+  --telegram-token <token>
+  --no-telegram                        (clear the saved token; disables Telegram in the guest)
+  --telegram-users <csv>
+  --model <id>
+  --skills <csv>
+  --openclaw-image <image>
+  --anthropic-api-key <key>
+  --openai-api-key <key>
+  --minimax-api-key <key>
+  --skip-browser-install
+  --browser-install                    (re-enable browser install)
+  -h|--help
 EOF
 }
 
-[[ $# -eq 1 ]] || { usage; exit 1; }
+csv_values() {
+  printf '%s' "$1" | tr ',' '\n' | sed 's/^[[:space:]]*//; s/[[:space:]]*$//; /^$/d'
+}
+
+validate_no_newline() {
+  local name="$1"
+  local value="$2"
+  [[ "$value" != *$'\n'* && "$value" != *$'\r'* ]] || die "$name must not contain newlines"
+}
+
+require_option_value() {
+  local opt="$1"
+  local value="${2-}"
+  [[ -n "$value" && "$value" != --* ]] || die "Missing value for $opt"
+}
+
+set_kv() {
+  local file="$1"
+  local key="$2"
+  local value="$3"
+  local tmp
+  validate_no_newline "key" "$key"
+  validate_no_newline "$key" "$value"
+  tmp="$(mktemp)"
+  awk -F= -v key="$key" '$1 != key { print }' "$file" > "$tmp"
+  printf "%s=%s\n" "$key" "$value" >> "$tmp"
+  install -m 600 "$tmp" "$file"
+  rm -f "$tmp"
+}
+
+saved_value() {
+  local file="$1"
+  local key="$2"
+  grep "^$key=" "$file" | tail -n 1 | cut -d= -f2- || true
+}
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" || "${1:-}" == "help" ]]; then
+  usage
+  exit 0
+fi
+
+[[ $# -ge 1 ]] || { usage; exit 1; }
 
 INSTANCE="$1"
+shift
+
+declare -A OVERRIDES=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --telegram-token) require_option_value "$1" "${2-}"; OVERRIDES[TELEGRAM_TOKEN]="$2"; shift 2 ;;
+    --no-telegram) OVERRIDES[TELEGRAM_TOKEN]=""; shift ;;
+    --telegram-users) require_option_value "$1" "${2-}"; OVERRIDES[TELEGRAM_USERS]="$2"; shift 2 ;;
+    --model) require_option_value "$1" "${2-}"; OVERRIDES[MODEL]="$2"; shift 2 ;;
+    --skills) require_option_value "$1" "${2-}"; OVERRIDES[SKILLS]="$2"; shift 2 ;;
+    --openclaw-image) require_option_value "$1" "${2-}"; OVERRIDES[OPENCLAW_IMAGE]="$2"; shift 2 ;;
+    --anthropic-api-key) require_option_value "$1" "${2-}"; OVERRIDES[ANTHROPIC_API_KEY]="$2"; shift 2 ;;
+    --openai-api-key) require_option_value "$1" "${2-}"; OVERRIDES[OPENAI_API_KEY]="$2"; shift 2 ;;
+    --minimax-api-key) require_option_value "$1" "${2-}"; OVERRIDES[MINIMAX_API_KEY]="$2"; shift 2 ;;
+    --skip-browser-install) OVERRIDES[SKIP_BROWSER_INSTALL]="true"; shift ;;
+    --browser-install) OVERRIDES[SKIP_BROWSER_INSTALL]="false"; shift ;;
+    *)
+      die "Unknown option: $1"
+      ;;
+  esac
+done
+
 validate_instance_id "$INSTANCE"
 require_root
 
+# load_instance_env resets the key variables from saved state, so remember
+# what the caller passed in the environment before it runs.
+ENV_ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY:-}"
+ENV_OPENAI_API_KEY="${OPENAI_API_KEY:-}"
+ENV_MINIMAX_API_KEY="${MINIMAX_API_KEY:-}"
+
 load_instance_env "$INSTANCE"
 
+ENV_FILE="$(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
+if [[ -n "${OVERRIDES[TELEGRAM_USERS]:-}" ]]; then
+  [[ -n "$(csv_values "${OVERRIDES[TELEGRAM_USERS]}")" ]] || die "--telegram-users must include at least one allowed Telegram user ID"
+fi
+
+effective() {
+  local key="$1"
+  local fallback="$2"
+  if [[ -v "OVERRIDES[$key]" ]]; then
+    printf '%s' "${OVERRIDES[$key]}"
+  else
+    printf '%s' "$fallback"
+  fi
+}
+
+# Keys passed via the environment fill in for empty saved values, matching
+# the behavior the provider-key error message advertises.
+if [[ -z "$(effective ANTHROPIC_API_KEY "${ANTHROPIC_API_KEY:-}")" && -n "$ENV_ANTHROPIC_API_KEY" ]]; then
+  OVERRIDES[ANTHROPIC_API_KEY]="$ENV_ANTHROPIC_API_KEY"
+fi
+if [[ -z "$(effective OPENAI_API_KEY "${OPENAI_API_KEY:-}")" && -n "$ENV_OPENAI_API_KEY" ]]; then
+  OVERRIDES[OPENAI_API_KEY]="$ENV_OPENAI_API_KEY"
+fi
+if [[ -z "$(effective MINIMAX_API_KEY "${MINIMAX_API_KEY:-}")" && -n "$ENV_MINIMAX_API_KEY" ]]; then
+  OVERRIDES[MINIMAX_API_KEY]="$ENV_MINIMAX_API_KEY"
+fi
+
+# Validate the post-override view BEFORE persisting anything, so a rejected
+# run leaves the saved config exactly as it was.
+EFFECTIVE_TELEGRAM_TOKEN="$(effective TELEGRAM_TOKEN "$(saved_value "$PROVISION_VARS" TELEGRAM_TOKEN)")"
+EFFECTIVE_TELEGRAM_USERS="$(effective TELEGRAM_USERS "${TELEGRAM_USERS:-}")"
+if [[ -n "$EFFECTIVE_TELEGRAM_TOKEN" ]]; then
+  if [[ -z "$(csv_values "$EFFECTIVE_TELEGRAM_USERS")" ]]; then
+    die "Telegram is enabled but TELEGRAM_USERS is empty; rerun with: sudo $CMD_NAME $INSTANCE --telegram-users <csv>"
+  fi
+fi
+
+EFFECTIVE_MODEL="$(effective MODEL "${MODEL:-}")"
+ANTHROPIC_API_KEY="$(effective ANTHROPIC_API_KEY "${ANTHROPIC_API_KEY:-}")"
+OPENAI_API_KEY="$(effective OPENAI_API_KEY "${OPENAI_API_KEY:-}")"
+MINIMAX_API_KEY="$(effective MINIMAX_API_KEY "${MINIMAX_API_KEY:-}")"
+require_model_provider_key "$EFFECTIVE_MODEL"
+
+# TELEGRAM_TOKEN lives only in provision.vars; every other key is mirrored
+# into the .env state file that load_instance_env reads.
+for key in "${!OVERRIDES[@]}"; do
+  set_kv "$PROVISION_VARS" "$key" "${OVERRIDES[$key]}"
+  if [[ "$key" != "TELEGRAM_TOKEN" ]]; then
+    set_kv "$ENV_FILE" "$key" "${OVERRIDES[$key]}"
+  fi
+done
+
+if ! wait_for_ssh "$VM_IP" "$SSH_KEY_PATH" 180 "$INSTANCE"; 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 \
+scp -i "$SSH_KEY_PATH" -o StrictHostKeyChecking=accept-new -o UserKnownHostsFile="$(ssh_known_hosts_file "$INSTANCE")" \
   "$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 \
+scp -i "$SSH_KEY_PATH" -o StrictHostKeyChecking=accept-new -o UserKnownHostsFile="$(ssh_known_hosts_file "$INSTANCE")" \
   "$PROVISION_VARS" "ubuntu@$VM_IP:/tmp/provision.vars"
 
-ssh -i "$SSH_KEY_PATH" -o StrictHostKeyChecking=accept-new -o UserKnownHostsFile=/dev/null \
+ssh -i "$SSH_KEY_PATH" -o StrictHostKeyChecking=accept-new -o UserKnownHostsFile="$(ssh_known_hosts_file "$INSTANCE")" \
   "ubuntu@$VM_IP" "sudo bash /tmp/provision-guest.sh /tmp/provision.vars"
 
-systemctl enable --now "$(proxy_service "$INSTANCE")" >/dev/null 2>&1 || true
+systemctl enable --now "$(proxy_service "$INSTANCE")"
 
-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
+if ! wait_for_instance_health "$INSTANCE" "$VM_IP" "$HOST_PORT" "$SSH_KEY_PATH" 30; then
+  die "Health checks did not pass for $INSTANCE after provisioning"
+fi
 
 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
+echo "  Health:   up (guest + proxy)"