isopod

Run untrusted code in a real microVM. Boots in ~0.4 s, destroyed after every call.

isopod gives coding agents somewhere to run commands that isn't your machine. Each call boots a Firecracker microVM, runs one command inside it, and throws the VM away. Isolation is the KVM hardware boundary, not a shared kernel.

• Fast enough to use per-action — ~0.4 s cold, ~49 ms from the warm pool (measured).
• Egress allowlists the guest cannot rewrite. Name the hosts a run may reach; everything else fails closed. Enforced by nftables and a host-side broker, outside the sandbox.
• A flight recorder for the network. Every destination allowed and refused, every name resolved, with byte volumes — so you can watch a dependency try to phone home.
• Nothing from your filesystem is shared in. No bind mounts, no 9p. Files move only over explicit RPC.
• Environments persist as stages, not long-lived sandboxes. Commit what a run changed, fork it later; content-addressed and immutable.
• One core, two front ends — an MCP server for Claude Code and a CLI for humans and CI.
• Auditable. The whole enforcement path is a few files of Rust you can read, and the security claims ship with the bypass attempts that test them.

📖 Documentation · Security model · Benchmarks · Changelog

sandbox_run(cmd="pip install requests", allow_hosts=["pypi.org", "*.pythonhosted.org"])

Pre-1.0 and moving quickly; main is the supported line. Newest (0.20.1, changelog): image build-all works again — Alpine's CDN had superseded the pinned apk-tools-static, so every base-alpine build 404'd — and rustls is updated for RUSTSEC-2026-0285. Since 0.19.0: a read-only jail bind is read-only including every mount beneath it — it was not, and said nothing — which makes Linux 5.12 a requirement for the opt-in jail and for nothing else. Also since 0.14.0: guest egress survives a coexisting Docker install, which used to swallow it silently, and a NAT run gets a host-side DNS resolver instead of baked-in public ones. An existing host needs one sudo isopod setup to pick up the forward-hook and resolver provisioning.

---

Quick start

Prerequisites: Linux x86_64 with /dev/kvm (your user in the kvm group). Full details, WSL2 notes, and troubleshooting: docs/getting-started.md.

Option A — install a release package. Grab the .deb, .rpm, or tarball from the releases page; it ships the CLI, the MCP server, the jail helper, and prebuilt Firecracker + guest-agent binaries, so no Rust toolchain or source build is needed:

sudo apt install ./isopod_*_amd64.deb   # or: sudo dnf install ./isopod-*.x86_64.rpm

isopod image fetch-kernel   # pinned, digest-verified guest kernel
isopod image build-all      # guest rootfs images (unprivileged)
sudo isopod setup           # one-time host networking — the only root step
                            # (sudo drops ~/.local/bin from PATH: use an
                            #  explicit path, e.g. sudo ~/.local/bin/isopod setup)
isopod run --stage base --base base-alpine -- python3 -c 'print("hello from a microVM")'

Option B — build from source (needs Rust via rustup, nftables iproute2 e2fsprogs squashfs-tools, and a C toolchain):

git clone https://github.com/me1iissa/isopod.git
cd isopod
git submodule update --init --recursive     # vendored Firecracker v1.16.1
cargo build --release

./target/release/isopod dev build-fc        # build Firecracker -> ~/.isopod/bin
./target/release/isopod image fetch-kernel
./target/release/isopod image build-all
sudo ./target/release/isopod setup
./target/release/isopod run --stage base --base base-alpine -- \
  python3 -c 'print("hello from a microVM")'

To drive it from Claude Code, install the plugin — it registers the MCP server and a workflow skill in one step:

/plugin marketplace add me1iissa/isopod
/plugin install isopod@isopod
/reload-plugins
# then:  sandbox_run(cmd="echo hi")

Install isopod itself first, using either option above. The plugin wires isopod into your client; it does not contain isopod, because a sandbox also needs /dev/kvm, a Firecracker binary, guest images and one sudo isopod setup. If the server cannot be found, the plugin says so and prints these steps rather than failing silently.

Or register the MCP server directly, without the plugin:

claude mcp add --scope local isopod -- /usr/bin/isopod-mcp            # package install
claude mcp add --scope local isopod -- "$PWD/target/release/isopod-mcp"  # source checkout

---

Why

Agents need somewhere fast and safe to run commands, build code, and execute untrusted or experimental workloads. Containers are heavy to set up, slow to tear down cleanly, and share the host kernel. Firecracker microVMs give hardware isolation with sub-second cold boots and single-digit-millisecond snapshot restores — the right fit for a one action, one sandbox agent cadence.

isopod is built around a single idea:

This is the beginning of the README. Read the rest at the original. Read the full README ↗