Bunkervm
Self-hosted AI sandbox with hardware isolation. Firecracker microVMs give each AI agent its own Linux machine — boots in 3s, destroyed after use. Works with LangChain, OpenAI, CrewAI, VS Code Copilot. No cloud. No Docker. Free (Apache-2.0).
Install / Use
/learn @ashishgituser/BunkervmQuality Score
Category
Development & EngineeringSupported Platforms
README
The problem
AI agents execute code on your machine. When something goes wrong — and it will — you have no way to see what the agent actually did, rewind to the moment before it broke, or compare why one agent succeeded and another failed.
Containers share your kernel (escapes are real).
Cloud sandboxes send your data to someone else's server.
Neither gives you observability into agent behaviour.
BunkerVM solves all three: isolation, observability, and time-travel.
What it does
Each sandbox is a Firecracker microVM — the same technology behind AWS Lambda. Own kernel, own filesystem, hardware-level (KVM) isolation. Not a container.
On top of that, BunkerVM adds capabilities that no other sandbox provides:
Record every execution
from bunkervm import Sandbox
with Sandbox(record=True) as sb:
sb.run("import pandas as pd")
sb.run("df = pd.read_csv('/data/input.csv')")
sb.run("df['total'] = df.price * df.qty")
sb.run("df.to_csv('/output/result.csv')")
# Every step recorded: command, output, filesystem changes, VM snapshot
Rewind to any point
sb.restore(step=2) # VM state rewinds to after read_csv
sb.run("df.describe()") # explore from that exact point
The VM's memory, CPU registers, filesystem — everything reverts to exactly what it was after step 2. Not a re-run. An actual restore from a Firecracker snapshot.
See what changed
for cp in sb.history():
print(f"step {cp['step']}: {cp['command']}")
if cp['trace']:
for f in cp['trace']['files_created']:
print(f" + {f['path']} ({f['size']} bytes)")
step 1: import pandas as pd
step 2: df = pd.read_csv('/data/input.csv')
~ /data/input.csv (read)
step 3: df['total'] = df.price * df.qty
step 4: df.to_csv('/output/result.csv')
+ /output/result.csv (1247 bytes)
Compare two agents
bunkervm diff session-abc session-def
Agent Diff
Session A: abc (12 steps, 3400ms)
Session B: def (8 steps, 1200ms)
Files only in A: /tmp/debug.log, /tmp/retry_3.py
Files only in B: /output/result.csv
step 1 [same] import pandas as pd
step 2 [same] df = pd.read_csv('/data/input.csv')
step 3 [diff]
A: df = df.dropna()
B: df = df.fillna(0)
step 4 [diff]
A: # crashed — KeyError: 'total'
B: df['total'] = df.price * df.qty ← OK
Agent A dropped rows and lost a required column. Agent B filled missing values and succeeded. Without diff, you'd never know why.
Quick start
pip install bunkervm
from bunkervm import run_code
result = run_code("print('Hello from a microVM!')")
print(result) # Hello from a microVM!
VM boots, code runs, VM dies. Your host was never touched.
How it works
AI Agent
│
▼
bunkervm (host) ──vsock──▶ Firecracker MicroVM
│ ┌────────────────────┐
│ record=True │ Alpine Linux │
│ ─────────▶ │ Own kernel │
│ snapshot() │ exec_agent.py │
│ trace() │ (filesystem trace) │
│ restore() └────────────────────┘
│ KVM hardware isolation
▼
~/.bunkervm/sessions/ ~/.bunkervm/snapshots/
session-abc.json step1/ vmstate + memory
session-def.json step2/ vmstate + memory
Firecracker provides the isolation. BunkerVM adds the instrumentation layer:
| Layer | What it does |
|---|---|
| exec_agent (inside VM) | Traces filesystem changes per command — files created, modified, deleted, bytes written |
| Firecracker API (host→VM) | Pauses VM, snapshots CPU + memory state to disk, resumes — all via Firecracker's built-in snapshot API |
| Snapshot manager (host) | Stores and indexes snapshots at ~/.bunkervm/snapshots/, manages lifecycle |
| Session recorder (host) | Chains commands → traces → snapshots into a replayable session JSON |
No custom kernel modules. No eBPF. No ptrace. The VM is the isolation boundary; the API socket is the control plane. Pure Python, stdlib-only transport.
The four capabilities
1. Filesystem tracing
Every command execution can return a trace of what changed on disk.
result = client.exec("python3 train.py", trace=True)
print(result["trace"])
# {
# "files_created": [{"path": "/output/model.pkl", "size": 4820}],
# "files_modified": [{"path": "/tmp/loss.log", "old_size": 0, "new_size": 312}],
# "files_deleted": [],
# "bytes_written": 5132
# }
This happens inside the VM — a pre/post filesystem snapshot diff. No host-side hooks, no strace, no overhead on non-traced commands.
2. VM snapshots
Full VM state (CPU, memory, filesystem) saved to disk. Restore boots a new Firecracker process from that state instead of cold-booting.
from bunkervm import Sandbox
with Sandbox() as sb:
sb.run("import torch; model = torch.load('bert.pt')")
sb.checkpoint("model-loaded") # snapshot: 45ms
sb.run("output = model(bad_input)") # crashes
sb.restore(step=1) # restore: <100ms
sb.run("output = model(good_input)")# works
Snapshot = Firecracker's native PUT /snapshot/create. Not a filesystem copy. The memory file is sparse and CoW-friendly.
3. Session recording & replay
record=True automatically chains traces and snapshots into a session timeline.
# test_replay.py
from bunkervm import Sandbox
with Sandbox(record=True) as sb:
sb.run("x = 42")
print("Result:", sb.run("print(x * 2)"))
# Create directory first, then write file
sb.run("import os; os.makedirs('/tmp/output', exist_ok=True)")
sb.run("open('/tmp/output/result.txt', 'w').write(str(x))")
print("File content:", sb.run("print(open('/tmp/output/result.txt').read())"))
print("\nHistory:")
for step in sb.history():
print(f" Step {step['step']}: {step['command'][:60]}")
$ python test_replay.py
Starting sandbox via BunkerVM engine...
Sandbox ready (via engine).
Result: 84
File content: 42
History:
Step 1: x = 42
Step 2: print(x * 2)
Step 3: import os; os.makedirs('/tmp/output', exist_ok=True)
Step 4: open('/tmp/output/result.txt', 'w').write(str(x))
Step 5: print(open('/tmp/output/result.txt').read())
Session saved to ~/.bunkervm/sessions/d0c13cb74d85.json
Destroying sandbox...
Done.
bunkervm replay d0c13cb74d85 --trace
Session: d0c13cb74d85
Steps: 5
Recorded: 2026-03-29 23:15
Timeline:
step 1 [ok] 34ms x = 42
step 2 [ok] 23ms print(x * 2)
step 3 [ok] 22ms import os; os.makedirs('/tmp/output', exist_ok=True)
step 4 [ok] 21ms open('/tmp/output/result.txt', 'w').write(str(x))
step 5 [ok] 21ms print(open('/tmp/output/result.txt').read())
Each 📸 = a restorable VM snapshot. You can restore(step=2) and branch from there.
4. Agent diff
Run the same task with two different agents (or prompts, or models). Record both. Diff.
bunkervm diff session-gpt4 session-claude --format json
The diff shows: which files each agent created, which steps diverged, which agent was faster, and where failures happened. This is how you debug agent quality — not by reading logs, but by comparing filesystem-level behaviour.
Framework integrations
Every integration auto-boots a VM and exposes 6 sandboxed tools. One base class, identical behaviour across frameworks.
<details> <summary><strong>LangChain / LangGraph</strong></summary>pip install bunkervm[langgraph] langchain-openai
from bunkervm.langchain import BunkerVMToolkit
with BunkerVMToolkit() as toolkit:
tools = toolkit.get_tools() # run_command, write_file, read_file, ...
# pass tools to your agent
pip install bunkervm[openai-agents]
from bunkervm.openai_agents import BunkerVMTools
tools = BunkerVMTools()
agent_tools = tools.get_tools()
# ...
tools.stop()
pip install bunkervm[crewai]
from bunkervm.crewai import BunkerVMCrewTools
tools = BunkerVMCrewTools()
crew_tools = tools.get_tools()
# ...
tools.stop()
