firectl

Command-line launcher for Firecracker microVMs

TLDR

Start a VM with kernel and root disk

$ firectl --kernel=[./vmlinux] --root-drive=[/path/image.img]

Custom Firecracker binary path

$ firectl --firecracker-binary=[/usr/local/bin/firecracker] --kernel=[./vmlinux] --root-drive=[disk.img]

More CPUs and memory

$ firectl --kernel=[./vmlinux] --root-drive=[disk.img] -c [2] -m [1024]

With TAP networking

$ firectl --kernel=[./vmlinux] --root-drive=[disk.img] --tap-device=[tap0/AA:FC:00:00:00:01]

Writable root and custom kernel cmdline

$ firectl --kernel=[./vmlinux] --root-drive=[disk.img:rw] --kernel-opts="console=ttyS0 reboot=k panic=1 pci=off nomodules rw"

firectl is a basic command-line tool to run Firecracker microVMs with console access, disk I/O, and optional networking. It wraps the firecracker binary: you supply a Linux kernel image (vmlinux) and root filesystem image, plus optional extra drives, TAP NIC, vsock, CPU/memory, and MMDS metadata.By default it searches PATH for firecracker. Build with Go 1.23+ (go build or make build-in-docker). Needs KVM access (for example setfacl on /dev/kvm).

PARAMETERS

--firecracker-binary=path

Path to the firecracker binary.

--kernel=path

Kernel image (default ./vmlinux).

--kernel-opts=cmdline

Kernel command line.

--root-drive=path[:ro|:rw]

Root disk image, optional :ro or :rw suffix.

--add-drive=path[:ro|:rw]

Additional drive (repeatable).

--tap-device=DEVICE/MAC

TAP NIC configuration.

--vsock-device=PATH:CID

Vsock interface (repeatable).

-c, --ncpus=n / -m, --memory=MiB

vCPU count (default 1) and memory in MiB (default 512).

--cpu-template=C3|T2

Firecracker CPU template.

-t, --disable-smt

Disable simultaneous multithreading.

-s, --socket-path=path

Firecracker API socket path.

-d, --debug

Debug output.

See firectl --help for log FIFOs, metrics, metadata JSON, and partition options.

INSTALL

sudo zypper install firectl

nix profile install nixpkgs#firectl

CAVEATS

Requires hardware virtualization (KVM) and a working Firecracker install. Kernel and rootfs must be Firecracker-compatible. Root/network setup often needs elevated privileges. Not a full orchestration stack (see Firecracker docs and tools like flintlock for production fleets).

RESOURCES

Source code · Homepage