Machines | Kiln

Open it, use it, stop it.

kiln vm open dev
Starts the VM if it is stopped, waits for the guest agent and attaches a terminal.
kiln vm exec dev -- uname -a
Runs one command. Pipe a file in and Kiln streams it to the command's standard input.
kiln vm forward dev 3000
Listens on a free loopback port and tunnels it to port 3000 in the guest.
kiln vm stop dev
Asks the guest to sync and power off before Kiln stops the machine.
kiln vm start dev
Boots it again on the same disk.
kiln vm delete dev
Deletes the VM and its disk. The cached profile image stays.

Linux guests boot on Firecracker. Windows 11 boots on QEMU.

Kiln builds each profile image once for a given disk size and caches it. Every VM starts as its own writable copy of that image.

kiln vm create builds the image when it needs to. Run ensure first if you would rather pay that cost ahead of time.

kiln vm images ensure ubuntu --disk 8G

Kiln ships no Windows media or licence keys. You supply the ISO, and Kiln prepares the profile from it once.

kiln profile prepare windows11 --iso /path/to/Win11.iso

alpine: Small Linux for smoke tests and light tooling
debian: Debian stable
ubuntu: Ubuntu LTS
kali: Kali rolling, headless
ubuntu-docker: Ubuntu with Docker, rsync, SSH, Postgres client tools and build essentials
windows11: Windows 11, prepared once from your own ISO

A role fills in the shape.

A role is an alias for ordinary create flags. It resolves to a profile, CPU, memory, disk and power mode, and any flag you pass overrides it.

kiln vm roles kiln vm create bourne-runner --role ci-runner --dry-run

builder: A warm Docker build VM with more CPU and memory than the default.
ci-runner: An always-on Docker VM sized for self-hosted CI runners.
docker-worker: An on-demand Docker VM for short build and test jobs.

What a stop keeps, and what a start rewrites.

Changes inside the VM go to its own root filesystem. They survive kiln vm stop, kiln vm start and restarts of kilnd.

Before each boot of a Linux guest, Kiln rewrites five files on that disk and no others. Windows guests get none of these writes.

These VMs are headless.

They suit shells, installed tools, package state and isolated service testing. Kiln has no GUI desktops, USB passthrough or Wi‑Fi monitor mode, so it does not replace a desktop hypervisor.

/root/.ssh/authorized_keys: Kiln replaces its own key line and keeps every other line.
/etc/hostname: Set to vm-<name>.
/etc/hosts: Kiln adds missing localhost and hostname entries and keeps the rest.
/etc/resolv.conf: Replaced with Kiln's guest DNS servers when the host configures any.
/etc/kiln/private-network.json: Written when the VM is on a private network, removed when it is not.

CPU is a time budget.

--cpu sets how much CPU time the VM may use. The number of vCPUs the guest sees comes from the profile unless you pass --vcpus.

kiln vm create ci --profile ubuntu-docker --disk 128G --memory-mb 12288 --cpu 6 --vcpus 6

Share one pool

Set KILN_POOLED_CPU_LIMIT on the host and create guests with --cpu-kind pooled. Each guest can use spare capacity, and one quota caps the pool as a whole.

Use a systemd slice

Pass --slice ci.slice and the VM runs under that slice's CPU and memory policy. You define the slice. Kiln only places the VM in it.