Knaller

Node-local Firecracker microVM runtime for an IONOS Cloud Cube.

Knaller is the German word for "firecracker" (/ˈknalɐ/, roughly KNALL-er).

A single Ubuntu host runs many isolated microVM sandboxes. The knaller CLI creates, starts, stops, lists, inspects, and deletes sandboxes subject to host capacity. Each sandbox runs under Firecracker jailer with its own Linux user, network namespace, cloned rootfs, and TAP/veth networking. systemd supervises the lifecycle via knaller@… units.

The repo evolved from a static two-VM setup (v1.0.0) into this generic node-local runtime. See the roadmap for current progress.

CLI

knaller capacity          # host resources and what is still free
knaller create            # provision a new sandbox
knaller list              # running and stopped sandboxes
knaller inspect <name>    # full sandbox state and paths
knaller start <name>      # start via systemd
knaller stop <name>       # graceful shutdown
knaller delete <name>     # tear down sandbox and storage
knaller config validate   # check /etc/knaller/config.yaml

Creation examples (target):

knaller create --name web-1 --cpus 2 --memory 512
knaller create --name worker-1 --cpus 1 --memory 256

Admission enforces strict RAM limits and configurable CPU overcommit. Provisioning clones a shared base rootfs, assigns sandbox-local resources, UID/GID, guest and transit subnets, generates Firecracker config, wires networking, and persists state for reboot-safe operation.

Higher-level sizing and fleet placement are intentionally outside Knaller.

Repository layout

• cmd/knaller/ - CLI entrypoint
• internal/ - config, capacity, scheduler, state, allocate, storage, ...
• config/ - example host configuration
• host/ - jailer helpers, host networking, systemd units
• guests/ - legacy static VM configs (vm1, vm2; replaced by dynamic flow)
• scripts/ - image and host build automation
• artifacts/ - artifact manifests and checksums
• versions.env - pinned software and kernel versions

Host runtime layout

/etc/knaller/config.yaml

/var/lib/knaller/images/
  base-rootfs.ext4
  vmlinux-6.18.44

/var/lib/knaller/state/
  vm-0001.json
  vm-0002.json

/var/lib/knaller/vms/<vm-id>/
  config.json
  rootfs.ext4
  vmlinux

/srv/jailer/firecracker/<vm-id>/   # disposable jail state

systemd: knaller@.service, knaller-network@.service

The current implementation derives UID/GID, network namespaces, and /30 guest/transit networks from deterministic vm-NNNN allocations. The next runtime stage separates permanent sandbox identity from reusable node-local slots while preserving deterministic local resource allocation.

Roadmap

• v1.0.0 static two-VM baseline
• Go CLI skeleton
• Config loading
• Capacity reporting
• Sandbox state model
• Scheduler / node-local admission
• Resource allocation
• Base-rootfs workflow
• Firecracker config
• Runtime state / lifecycle foundations
• Generic jailer / supervision
• Generic networking / default isolation
• create / delete with rollback
• list / inspect / start / stop
• Resource enforcement
• doctor / reconcile
• Fault / reboot testing
• Golden image / clean-room test
• Zunder integration