# sandkiln

> Docs for sandkiln -- a compute primitive for safely running untrusted or AI-generated code in hardware-isolated Firecracker microVMs.

- [sandkiln docs](https://sandkiln.mintlify.app/index.md): Docs for sandkiln — a compute primitive for safely running untrusted or AI-generated code in hardware-isolated Firecracker microVMs.
- [Introduction](https://sandkiln.mintlify.app/getting-started/introduction.md): What sandkiln is, how it's shaped, and where to go next.
- [Self-hosting quickstart](https://sandkiln.mintlify.app/getting-started/self-hosting.md): Get a sandkilnd daemon running from a bare Linux host — step by step, with the failures you're likely to actually hit.
- [First sandbox: JS/TS](https://sandkiln.mintlify.app/getting-started/js.md): Boot and run your first sandbox with the JS/TS SDK.
- [First sandbox: Python](https://sandkiln.mintlify.app/getting-started/python.md): Boot and run your first sandbox with the Python SDK.
- [First sandbox: CLI](https://sandkiln.mintlify.app/getting-started/cli.md): Boot and run your first sandbox with kiln.
- [Sandbox lifecycle](https://sandkiln.mintlify.app/concepts/sandbox-lifecycle.md): Create, list, and stop — the core operations every client wraps.
- [Snapshots, resume, and fork](https://sandkiln.mintlify.app/concepts/snapshots.md): Save a sandbox's full state to disk and boot from it later.
- [Named sandboxes & persistent stop](https://sandkiln.mintlify.app/concepts/named-sandboxes.md): Give a sandbox an identity you can find again by name.
- [Drives](https://sandkiln.mintlify.app/concepts/drives.md): Persistent filesystem storage that outlives a single sandbox.
- [Remote storage mounts](https://sandkiln.mintlify.app/concepts/remote-storage.md): Mount an S3-compatible bucket into a sandbox and read and write it as an ordinary directory.
- [Custom & managed images](https://sandkiln.mintlify.app/concepts/images.md): Boot sandboxes from your own registered rootfs image.
- [Networking & isolation](https://sandkiln.mintlify.app/concepts/networking.md): How sandboxes reach the internet, and why they can't reach each other.
- [Auth](https://sandkiln.mintlify.app/concepts/auth.md): Bearer-token authentication, and how every client resolves it.
- [Dev-server preview](https://sandkiln.mintlify.app/concepts/preview.md): Reach a server running inside a sandbox from a browser.
- [Local tunnel](https://sandkiln.mintlify.app/concepts/local-tunnel.md): Expose a service on your own machine to code running inside a sandbox — the reverse of preview.
- [Run untrusted AI-generated code safely](https://sandkiln.mintlify.app/guides/run-untrusted-code.md): The default, no-configuration-needed path for executing code you don't trust.
- [Persist state across runs by name](https://sandkiln.mintlify.app/guides/persist-by-name.md): Give a sandbox an identity you can find again tomorrow.
- [Share a drive read-only](https://sandkiln.mintlify.app/guides/share-a-drive.md): Attach the same drive to many sandboxes at once.
- [Boot from a custom image](https://sandkiln.mintlify.app/guides/custom-image.md): Register a rootfs and boot sandboxes from it.
- [Auto-suspend idle sandboxes](https://sandkiln.mintlify.app/guides/auto-suspend.md): Reclaim resources from forgotten sandboxes automatically.
- [Changelog](https://sandkiln.mintlify.app/release-notes.md): Every real change, nothing rounded up -- tracks notable changes across the whole project.
- [HTTP API overview](https://sandkiln.mintlify.app/api-reference/http-api/overview.md): Base URL, auth, and a complete session in raw curl.
- [Sandboxes](https://sandkiln.mintlify.app/api-reference/http-api/sandboxes.md): Every /sandboxes route -- lifecycle, filesystem ops, exec-stream, snapshots, preview, and local tunnel.
- [Drives](https://sandkiln.mintlify.app/api-reference/http-api/drives.md): Persistent drives and remote storage (S3-compatible) mounts.
- [Images](https://sandkiln.mintlify.app/api-reference/http-api/images.md): Register, list, and delete custom rootfs images.
- [Pools](https://sandkiln.mintlify.app/api-reference/http-api/pools.md): Configure pre-warmed snapshot pools.
- [JS/TS SDK overview](https://sandkiln.mintlify.app/api-reference/js-sdk/overview.md): Install, configuration, and auth for the sandkiln npm package.
- [JS/TS: Sandbox](https://sandkiln.mintlify.app/api-reference/js-sdk/sandbox.md): Every Sandbox method -- lifecycle, filesystem, preview, tunnel, streamed exec, snapshots.
- [JS/TS: Image](https://sandkiln.mintlify.app/api-reference/js-sdk/image.md): Register, list, and delete custom rootfs images.
- [JS/TS: Drive](https://sandkiln.mintlify.app/api-reference/js-sdk/drive.md): Create, list, and delete persistent drives.
- [JS/TS: Pool](https://sandkiln.mintlify.app/api-reference/js-sdk/pool.md): Configure pre-warmed snapshot pools.
- [Python SDK overview](https://sandkiln.mintlify.app/api-reference/python-sdk/overview.md): Install, configuration, auth, and the Async* mirror classes.
- [Python: Sandbox](https://sandkiln.mintlify.app/api-reference/python-sdk/sandbox.md): Every Sandbox method -- lifecycle, filesystem, preview, tunnel, snapshots.
- [Python: Image](https://sandkiln.mintlify.app/api-reference/python-sdk/image.md): Register, list, and delete custom rootfs images.
- [Python: Drive](https://sandkiln.mintlify.app/api-reference/python-sdk/drive.md): Create, list, and delete persistent drives.
- [Python: Pool](https://sandkiln.mintlify.app/api-reference/python-sdk/pool.md): Configure pre-warmed snapshot pools.
- [CLI overview](https://sandkiln.mintlify.app/api-reference/cli/overview.md): Install, global options, and a complete kiln session.
- [kiln sandbox](https://sandkiln.mintlify.app/api-reference/cli/sandbox.md): Every kiln sandbox subcommand -- lifecycle, filesystem, preview, tunnel, snapshots.
- [kiln image](https://sandkiln.mintlify.app/api-reference/cli/image.md): Register, list, and delete custom rootfs images.
- [kiln drive](https://sandkiln.mintlify.app/api-reference/cli/drive.md): Create, list, and delete persistent drives.
- [kiln pool](https://sandkiln.mintlify.app/api-reference/cli/pool.md): Configure pre-warmed snapshot pools.
- [Overview](https://sandkiln.mintlify.app/architecture/overview.md): The Rust workspace, its four crates, and how a sandbox boots.
- [Startup latency & the pre-warmed pool](https://sandkiln.mintlify.app/architecture/startup-latency.md): The pre-warmed pool is shipped: what it actually buys, what it found, and what's still the real next lever.
- [Bug hunt: the vsock timeout that could hang a stop forever](https://sandkiln.mintlify.app/architecture/bug-hunt-vsock-timeout.md): A real bug found by actually running a full snapshot-then-stop cycle.
- [SDK and CLI design](https://sandkiln.mintlify.app/architecture/sdk-cli-design.md): Why both SDKs have zero runtime dependencies, why async Python is a fully separate class from sync, and why the CLI wraps the SDK instead of the HTTP API directly.
- [Testing and benchmarking](https://sandkiln.mintlify.app/architecture/testing-and-benchmarking.md): Unit tests, the 24-topic concurrent integration suite, load testing, and the criterion benchmarks behind every "live-verified" claim in these docs.
- [Engineering notebook: real bugs found building this](https://sandkiln.mintlify.app/architecture/engineering-notebook.md): What broke building interactive terminals, pre-warmed pools, snapshot lineage, time-travel restore, remote storage mounts, and streamed exec sessions. How each was actually found, and what's still genuinely unresolved.
- [SQLite: the history store](https://sandkiln.mintlify.app/internals/sqlite-history-store.md): What sandkiln's durable sandbox history is built on, and the pragma choice that cut a write's latency by ~51x.
- [Snapshot, resume, and fork: the mechanism](https://sandkiln.mintlify.app/internals/snapshot-resume-fork.md): What a Firecracker snapshot actually contains, why resume and fork are so different underneath, and the rootfs-sharing bug this project shipped and then fixed.
- [Drives: the mechanism](https://sandkiln.mintlify.app/internals/drives.md): What a Firecracker drive actually is on disk, and how sandkiln tracks who's allowed to hold one at once.
- [Images: the mechanism](https://sandkiln.mintlify.app/internals/images.md): What a rootfs image actually is at the filesystem level, and the honest limit on what sandkiln can verify about one.
- [vsock and the host-guest wire protocol](https://sandkiln.mintlify.app/internals/vsock-wire-protocol.md): What AF_VSOCK is, why sandkiln's guest protocol is a length-prefixed JSON frame, and the real bytes one exec sends over it.
- [The jailer and privilege model](https://sandkiln.mintlify.app/internals/jailer-privilege-model.md): What chroot, cgroups, and setuid actually do, why Firecracker's jailer drops privilege instead of running privileged, and the real state of this on sandkiln today.
- [iptables and per-sandbox egress policy](https://sandkiln.mintlify.app/internals/egress-iptables.md): What an iptables chain actually is, why sandkiln gives every sandbox its own, and a real allow_cidrs entry opening a blocked address back up.
- [TAP devices and bridge networking](https://sandkiln.mintlify.app/internals/tap-bridge-networking.md): What a TAP device and a Linux bridge actually are, why sandkiln pre-creates a fixed pool of them, and a real sandbox's live network assignment.
- [Internals: FUSE and rclone](https://sandkiln.mintlify.app/internals/fuse-rclone-mounts.md): What FUSE and rclone actually are, and how a mount is built from ordinary guest operations with no new wire protocol.
- [Internals: token-bucket rate limiting](https://sandkiln.mintlify.app/internals/rate-limiting.md): What a token bucket actually is, and why sandkiln exposes one simplified knob over Firecracker's own four independent limiters.
- [Internals: MMDS (guest metadata service)](https://sandkiln.mintlify.app/internals/mmds.md): How a sandbox's own id, name, and tags reach the guest without a network round-trip to the daemon.
- [Internals: PTY and forkpty](https://sandkiln.mintlify.app/internals/pty.md): What a pseudo-terminal actually is, and why an interactive shell needs a raw byte passthrough instead of sandkiln's usual request/response protocol.
- [Internals: exec-stream sessions](https://sandkiln.mintlify.app/internals/exec-stream.md): Why a detached background command needs its own buffering model, distinct from both batch exec and a PTY.
- [Internals: pre-warmed pools](https://sandkiln.mintlify.app/internals/pre-warmed-pools.md): Pre-warming as a general latency-hiding technique, and how sandkiln's replenisher keeps a pool topped up in the background.
- [Local tunnel: the mechanism](https://sandkiln.mintlify.app/internals/local-tunnel.md): Why exposing a service on the caller's machine needed a guest-initiated vsock connection, the one exception to this protocol's own direction rule, and the hand-rolled WebSocket client that carries it the rest of the way.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.