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://sandkiln.vercel.app (architecture, real benchmark
numbers, live feature status, and startup-latency research). Full docs
(getting started, guides, API/SDK/CLI reference) at
https://sandkiln.mintlify.site/.
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 at https://sandkiln.vercel.app:
architecture, benchmarks, roadmap.docs-site/ — the full docs site (getting started, core concepts,
guides, API/SDK/CLI reference, architecture), a separate Mintlify
project — see https://sandkiln.mintlify.site/.
License
MIT
