kiln

A harness you put on your app before you launch it into the wall.

kiln v5 is a deterministic, mechanical testing harness for CLI tools and software projects. It applies maximum pressure to a target and reports exactly what broke, how, and under what conditions. It has no opinions about how to fix what it finds — that is the developer's job.

Kiln contains no AI, no model clients, no API keys, and makes no network calls during normal operation. Same seed, same pressure, same findings. Every run is reproducible by construction.

Install

git clone https://github.com/asha-software/kiln
cd kiln
zig build -Doptimize=ReleaseSafe
cp zig-out/bin/kiln /usr/local/bin/kiln

Or with nix:

nix run github:asha-software/kiln

Prerequisites: Zig 0.16.0, qemu-system-x86_64, bsdtar, curl. docker is optional (used for the service layer — Postgres, Redis tests).

Quickstart

kiln run               # run the test suite once
kiln watch             # run continuously until clean or max_loops reached
kiln break             # adversarial pressure campaign in a QEMU chamber
kiln ash               # show what's pending from the last run

Add --json to any command for the newline-delimited JSON event stream.

Modes

watch runs the suite in a loop. Each new failure is fingerprinted with Blake3, classified, and either routed to a chamber (env-dependent failures) or written to kiln/pending/ as a structured spec for external attention.

break is adversarial. It builds an attack surface from the project source, generates a deterministic pressure program, and — by default — runs it inside a disposable QEMU chamber across seven layers: boundary values, concurrency, resource starvation, longitudinal runs, fault injection, chaos combinations, and NixOS-specific adversarial state corruption. --explore follows up on Critical and High findings to narrow minimal reproductions.

temporal runs scripted multi-cycle workflows in a chamber, detecting what accumulates, drifts, or degrades over many cycles (store growth, generation leaks, output drift, performance cliffs).

visual boots a chamber with a display, captures a screenshot, and compares it pixel-by-pixel against a stored baseline in pure Zig.

fleet provisions and drives many chambers in parallel for large test operations.

The chamber

Serious pressure campaigns run inside a disposable QEMU VM built on a copy-on-write overlay. Everything that happens inside — corrupted Nix stores, filled disks, killed processes, temporal state accumulation — is contained and discarded when the overlay is deleted. The host filesystem is never touched. The accelerator is selected automatically: hvf on macOS, kvm on Linux, tcg as fallback.

Safety

Kiln never modifies, deletes, or creates files in the project source tree. The only permitted write target is kiln/. This is enforced by SafetyGuard, not convention: the source tree is snapshotted before every run and audited after, and any write outside kiln/ exits with code 2 — reserved exclusively for safety violations.

The blast radius of every destructive operation is bounded by construction: disk fill stays inside the sandbox, kill targets only Kiln-owned PIDs, file corruption only touches sandbox paths.

Configuration

Kiln works with zero configuration. To tune behaviour, run kiln init to write a starter kiln/kiln.toml. See kiln.md for the full manual and docs/kiln.1 for the man page.

License

Asha Software, 2026.