fireclaw

Run 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: 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
    ├── 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 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:

• 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

• Linux host with KVM support (/dev/kvm accessible)
• firecracker binary at /usr/local/bin/firecracker (install guide)
• 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.

Install

npm install -g fireclaw

Setup

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>"

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

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

# 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 (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

All scripts respect these overrides:

Variable	Default
STATE_ROOT	/var/lib/fireclaw
FC_ROOT	/srv/firecracker/vm-demo
BASE_PORT	18890
BRIDGE_NAME	fc-br0
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