Add repo guidelines and verify script

AGENTS.md

@@ -0,0 +1,33 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `run.sh` is the primary launcher script; it builds the per-VM state and configures Firecracker over the local API socket.
+- `firecracker`, `vmlinux`, and `rootfs.ext4` are runtime artifacts required to boot the guest.
+- `state/` is created at runtime to store per-VM sockets, logs, and metadata (safe to delete when no VMs are running).
+- `firecracker.log` is produced by Firecracker; additional per-VM logs live under `state/vm-*/`.
+
+## Build, Test, and Development Commands
+- `./run.sh` launches a VM using Firecracker, sets up a bridge/TAP device, and prints the guest IP plus SSH command.
+- `ssh -i "./id_ed25519" root@<guest_ip>` connects to the guest once it boots.
+- `reboot` (inside the guest) shuts down the VM.
+- There is no build step in this repo; binaries and images are checked in.
+
+## Coding Style & Naming Conventions
+- Shell scripts use Bash with `set -euo pipefail`; keep new scripts strict and explicit.
+- Indentation is two spaces in `run.sh`; match existing formatting and quoting style.
+- Filenames are short and descriptive (e.g., `run.sh`, `rootfs.ext4`). Prefer lowercase with dashes or dots.
+- No formatter or linter is configured; keep changes small and readable.
+
+## Testing Guidelines
+- No automated test framework is present.
+- Manual verification: run `./run.sh`, confirm the guest boots, and verify SSH access.
+- If adding tests, document how to run them in this file and keep them self-contained.
+
+## Commit & Pull Request Guidelines
+- Git history uses short, informal commit summaries (e.g., "ignore", "Document expected log noise").
+- Prefer imperative, single-line subjects; keep them under ~50 characters when possible.
+- PRs should describe the change, list any new runtime requirements, and include logs or screenshots if behavior changes.
+
+## Security & Configuration Tips
+- The script requires `sudo` and `/dev/kvm` access; avoid committing secrets or private keys.
+- `id_ed25519` is a local SSH key for the guest; rotate or replace it if sharing the repository.

run.sh

@@ -40,6 +40,24 @@ log "allocated guest ip: $GUEST_IP"
 
 sudo -v
 
+FC_USE_SUDO="${FC_USE_SUDO:-1}"
+FC_RUN=("$FC_BIN")
+CURL_CMD=(curl)
+if [[ "$FC_USE_SUDO" == "1" ]]; then
+  log "running firecracker with sudo (FC_USE_SUDO=1)"
+  FC_RUN=(sudo -E "$FC_BIN")
+  CURL_CMD=(sudo -E curl)
+fi
+
+if command -v setcap >/dev/null 2>&1; then
+  if ! getcap "$FC_BIN" 2>/dev/null | rg -q "cap_net_admin"; then
+    log "granting cap_net_admin to firecracker binary"
+    sudo setcap cap_net_admin+ep "$FC_BIN"
+  fi
+else
+  log "setcap not available; firecracker may need root to open TAP"
+fi
+
 # Host bridge
 if ! ip link show "$BR_DEV" >/dev/null 2>&1; then
   log "creating host bridge $BR_DEV ($BR_IP/$CIDR)"
@@ -48,20 +66,24 @@ if ! ip link show "$BR_DEV" >/dev/null 2>&1; then
   sudo ip link set "$BR_DEV" up
 else
   log "host bridge $BR_DEV already exists"
+  # Ensure existing bridge is up in case it was left down.
+  sudo ip link set "$BR_DEV" up
 fi
 
 # Per-VM TAP
 log "creating tap device $TAP_DEV"
-sudo ip tuntap add dev "$TAP_DEV" mode tap
+TAP_USER="${SUDO_UID:-$(id -u)}"
+TAP_GROUP="${SUDO_GID:-$(id -g)}"
+sudo ip tuntap add dev "$TAP_DEV" mode tap user "$TAP_USER" group "$TAP_GROUP"
 sudo ip link set "$TAP_DEV" master "$BR_DEV"
 sudo ip link set "$TAP_DEV" up
+sudo ip link set "$BR_DEV" up
 
 # Start Firecracker
 log "starting firecracker process"
 rm -f "$API_SOCK"
-nohup "$FC_BIN" --api-sock "$API_SOCK" >"$LOG_FILE" 2>&1 &
+nohup "${FC_RUN[@]}" --api-sock "$API_SOCK" >"$LOG_FILE" 2>&1 &
 FC_PID="$!"
-echo "$FC_PID" > "$VM_DIR/pid"
 log "firecracker pid: $FC_PID"
 
 # Wait for API socket
@@ -73,9 +95,18 @@ done
 [[ -S "$API_SOCK" ]] || { log "firecracker api socket not ready"; exit 1; }
 log "api socket ready"
 
+if [[ "$FC_USE_SUDO" == "1" ]]; then
+  SUDO_CHILD_PID="$(pgrep -n -f "$API_SOCK" || true)"
+  if [[ -n "$SUDO_CHILD_PID" ]]; then
+    FC_PID="$SUDO_CHILD_PID"
+    log "firecracker child pid: $FC_PID"
+  fi
+fi
+echo "$FC_PID" > "$VM_DIR/pid"
+
 # Machine config
 log "configuring machine"
-curl --unix-socket "$API_SOCK" -X PUT http://localhost/machine-config \
+"${CURL_CMD[@]}" --unix-socket "$API_SOCK" -X PUT http://localhost/machine-config \
   -H "Content-Type: application/json" \
   -d '{
     "vcpu_count": 2,
@@ -87,7 +118,7 @@ curl --unix-socket "$API_SOCK" -X PUT http://localhost/machine-config \
 log "configuring boot source"
 KCMD="console=ttyS0 reboot=k panic=1 pci=off root=/dev/vda rw ip=${GUEST_IP}::${BR_IP}:255.255.255.0::eth0:off"
 
-curl --unix-socket "$API_SOCK" -X PUT http://localhost/boot-source \
+"${CURL_CMD[@]}" --unix-socket "$API_SOCK" -X PUT http://localhost/boot-source \
   -H "Content-Type: application/json" \
   -d "{
     \"kernel_image_path\": \"$KERNEL\",
@@ -96,7 +127,7 @@ curl --unix-socket "$API_SOCK" -X PUT http://localhost/boot-source \
 
 # Root filesystem
 log "attaching root filesystem"
-curl --unix-socket "$API_SOCK" -X PUT http://localhost/drives/rootfs \
+"${CURL_CMD[@]}" --unix-socket "$API_SOCK" -X PUT http://localhost/drives/rootfs \
   -H "Content-Type: application/json" \
   -d "{
     \"drive_id\": \"rootfs\",
@@ -107,7 +138,7 @@ curl --unix-socket "$API_SOCK" -X PUT http://localhost/drives/rootfs \
 
 # Network interface
 log "configuring network interface"
-curl --unix-socket "$API_SOCK" -X PUT http://localhost/network-interfaces/eth0 \
+"${CURL_CMD[@]}" --unix-socket "$API_SOCK" -X PUT http://localhost/network-interfaces/eth0 \
   -H "Content-Type: application/json" \
   -d "{
     \"iface_id\": \"eth0\",
@@ -116,7 +147,7 @@ curl --unix-socket "$API_SOCK" -X PUT http://localhost/network-interfaces/eth0 \
 
 # Start VM
 log "starting virtual machine"
-curl --unix-socket "$API_SOCK" -X PUT http://localhost/actions \
+"${CURL_CMD[@]}" --unix-socket "$API_SOCK" -X PUT http://localhost/actions \
   -H "Content-Type: application/json" \
   -d '{ "action_type": "InstanceStart" }' >/dev/null
 
@@ -133,4 +164,3 @@ log "vm started successfully"
 log "guest ip: $GUEST_IP"
 log "ssh: ssh -i \"$SSH_KEY\" root@$GUEST_IP"
 log "logs: $LOG_FILE"
-

verify.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+log() {
+  printf '[verify] %s\n' "$*"
+}
+
+cleanup() {
+  if [[ -n "${VM_INFO:-}" && -f "$VM_INFO" ]]; then
+    # shellcheck disable=SC1090
+    source "$VM_INFO"
+    if [[ -n "${pid:-}" ]]; then
+      sudo kill "$pid" 2>/dev/null || true
+    fi
+    if [[ -n "${tap:-}" ]]; then
+      sudo ip link del "$tap" 2>/dev/null || true
+    fi
+    if [[ -n "${vm_dir:-}" ]]; then
+      rm -rf "$vm_dir"
+    fi
+  fi
+}
+
+trap cleanup EXIT
+
+log "starting VM"
+./run.sh
+
+VM_DIR="$(ls -dt state/vm-* | head -n 1)"
+VM_INFO="$VM_DIR/info"
+if [[ ! -f "$VM_INFO" ]]; then
+  log "info file not found: $VM_INFO"
+  exit 1
+fi
+
+# shellcheck disable=SC1090
+source "$VM_INFO"
+vm_dir="$VM_DIR"
+
+log "asserting VM is reachable via SSH"
+ssh -i "./id_ed25519" -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+  "root@${guest_ip}" "uname -a" >/dev/null
+
+log "cleaning up VM"
+cleanup
+
+log "asserting cleanup success"
+if ip link show "$tap" >/dev/null 2>&1; then
+  log "tap still exists: $tap"
+  exit 1
+fi
+if [[ -d "$vm_dir" ]]; then
+  log "vm dir still exists: $vm_dir"
+  exit 1
+fi
+
+log "ok"