English · Español

kindling

kindling runs microVMs — Firecracker on Linux, Virtualization.framework on macOS — that wake in milliseconds from frozen templates (golden snapshots) instead of booting. A frozen machine is a file on disk: it costs no CPU and no RAM until it is thawed, and it is isolated by a hypervisor, not by a shared kernel. It is one daemon and one CLI, kling, which grows through extensions.

Full documentation: kindling.asccilabs.com · in the repo: docs/, starting with the full guide.

Install

Linux with KVM (amd64 or arm64):

curl -fsSL https://raw.githubusercontent.com/juan52878911/kindling/main/scripts/install.sh | sh
kling up            # checks KVM, nftables, the kindling user and the images; prints what needs sudo

On arm64 (Graviton .metal, Ampere, Raspberry Pi 5 with the 4K kernel) see docs/linux-arm64.md for which hosts work and how to tune them.

The daemon can also run as a systemd service on a remote host, deployed from a checkout: make deploy HOST=ssh://user@host. The CLI then reaches it over SSH (kling context add lab ssh://user@host) — the daemon never listens on a network port.

Mac with Apple Silicon (macOS 14+, native vz backend, no root):

curl -fsSL https://raw.githubusercontent.com/juan52878911/kindling/main/scripts/install.sh | sh
brew install e2fsprogs
kling up            # downloads the guest kernel and the `min` image from the release, verified

Or with Homebrew, from the formula each release attaches (kling.rb; it pulls in e2fsprogs and brew services start kling runs the daemon):

curl -fsSLO https://github.com/juan52878911/kindling/releases/latest/download/kling.rb
brew install --formula ./kling.rb

The script verifies every binary against the release's SHA256SUMS, installs to ~/.local/bin without sudo, and takes --with mcp,sandbox, --tag vX.Y.Z and --prefix DIR. To upgrade later: kling upgrade (sudo on Linux; brew upgrade kling if Homebrew installed it) swaps the binaries, restarts the daemon, checks it and rolls back by itself if it fails. From source: make install (plus make vz on a Mac). Details: docs/mac.md, docs/releases.md, docs/actualizar.md (upgrades).

Try it

kling try -- uname -a        # throwaway microVM: create, run, print, delete
kling run -name demo         # boot a machine
kling freeze demo            # freeze it to disk: 0 CPU, 0 RAM
kling thaw demo              # back in tens of milliseconds

kling image import postgres:17-alpine -e POSTGRES_PASSWORD   # a Docker image, pinned by digest
kling run -image postgres-17-alpine -mem 512M -wait-ready     # its ENTRYPOINT, supervised

Docker images run as they are, each as its own base: docs/imagenes.md.

kling doctor checks the daemon, versions and extensions and gives the fix for every failure; kling help <command> shows one command's help.

Extensions

• kling mcp — any MCP server (npm or PyPI) as a service that wakes on demand from a golden snapshot, behind one gateway for your AI agent. ext/mcp
• kling sandbox — multi-tenant sandboxes for code agents: tokens, quotas, templates and a prewarmed pool. ext/sandbox
• kling db — a disposable Postgres (also MySQL, Redis, SQLite) per test or agent, copied from a warm template in milliseconds. docs/db.md
• kling phone — Android phones (Redroid) in microVMs, each with its own identity, a screen wall and an MCP server. ext/phone

Install one with kling plugin install <name>; every binary in a release is compatible with every other. Writing your own: docs/extensions.md.

Compatibility

kindling is still 0.x. From 1.0 on, the core (kling, the daemon, kling-guest, kling-vz), the daemon API, the Go packages pkg/api, pkg/plugin and pkg/config, the published kernel and min images, and the mcp and sandbox extensions follow SemVer: nothing stable breaks within 1.x, anything removed is deprecated first for at least two minor releases or six months, and kling upgrade moves from one release to the next and back. Templates and frozen machines are a cache: when the host can no longer restore one it is reported stale and refrozen, not migrated. db, phone, ai, Android, the Kubernetes operator, compose and kling-hv stay experimental. The full promise, and what is still missing before 1.0: docs/compatibilidad.md (in Spanish).

More

• SECURITY.md — the guest is assumed hostile: threat model, barriers and what is not solved yet.
• CHANGELOG.md — what each version brought.
• docs/benchmarks.md — every measured number and its hardware.
• docs/api.md — the daemon API, for talking to it from another program.

Apache-2.0 — see LICENSE and NOTICE.