sandkiln

A compute primitive for safely running untrusted or AI-generated code.

sandkiln boots hardware-isolated Firecracker microVMs on demand, gives you a programmatic API to execute commands and read/write files inside them, and tears them down when you're done. Each sandbox is a real microVM — its own kernel, its own filesystem, its own network namespace, isolated from every other sandbox on the same host. Built for the same shape of problem as AI agent sandboxes, code playgrounds, and untrusted-code execution services: isolate first, then run.

Website: https://sumitkumar-17.github.io/sandkiln/ (architecture, real benchmark numbers, live feature status, and startup-latency research) — also mirrored at https://sandkiln.vercel.app. Full docs (getting started, guides, API/SDK/CLI reference) at https://sumitkumar-17.github.io/sandkiln/docs/.

Quickstart

There's no hosted service — you run a sandkilnd daemon yourself. See SELF_HOSTING.md for the full setup (KVM, Firecracker, the base rootfs image, tap device pool, daemon config), then talk to it from a client.

npm install sandkiln

import { Sandbox } from "sandkiln";

const sandbox = await Sandbox.create({ tags: { env: "ci" } });
const result = await sandbox.runCommand("python3", ["analyze.py"]);
console.log(result.stdout, result.exitCode);
await sandbox.stop();

A CLI ships the same operations:

npm install -g sandkiln-cli   # installs the `kiln` command

Python mirrors the JS/TS SDK exactly too:

pip install sandkiln

See packages/python and packages/cli.

Status

Active development. The core primitive, networking, auth, tags, file ops, snapshot/resume/fork, named sandboxes, persistent-by-default stop, read-only shared drives, auto-suspend on idle, custom/managed images, per-sandbox I/O rate limiting, and all three clients (JS/TS, Python, CLI) work and are verified against real hardware — see CHANGELOG.md for what shipped and ROADMAP.md for what's still open (OCI-image conversion, multi-node, snapshot encryption at rest). The plan is a direction, not a spec, and keeps changing as the project gets built.

Picking this up as a contributor (human or agent)? Read AGENTS.md first — it covers non-obvious things this project already hit and fixed once.

Architecture

• core/ — Rust workspace: sandkiln-protocol (the wire format shared by host and guest), sandkiln-guest-agent (a static binary that runs inside each microVM), sandkiln-vmm (drives Firecracker and networking), sandkiln-store (durable sandbox-lifecycle history, sqlite), sandkiln-daemon (the HTTP API, sandkilnd).
• packages/sdk — sandkiln on npm, the JS/TS client.
• packages/python — sandkiln on PyPI, the Python client, mirroring the JS SDK exactly.
• packages/cli — kiln, the command-line interface.
• images/ — kernel and rootfs build scripts for sandbox base images.
• scripts/ — dev-box setup and daily-use tooling (dev.sh is the master dispatcher; one-time host provisioning lives under host-setup/, narrow manual-debugging tools under dev-tools/).
• website/ — the project site (deployed via GitHub Pages) and, in website/docs/, the full docs site (getting started, core concepts, guides, API/SDK/CLI reference, architecture) — see https://sumitkumar-17.github.io/sandkiln/docs/.

License

MIT