bunkervm 0.2.1

Hardware-isolated Linux sandbox for AI agents — Firecracker MicroVM + MCP

BunkerVM

Run AI agent code inside a Firecracker microVM instead of your host machine.

NervOS provides a lightweight sandbox for AI agents executing arbitrary code.

Give your AI agent a computer. Isolated. Instant. Self-hosted.

BunkerVM is a tiny operating system that boots in 2 seconds and gives AI agents a safe, isolated Linux machine to work in. Install it with one command. No Docker. No cloud. No config files.

Install

pip install bunkervm

Use with Claude Desktop

Add this to your Claude Desktop config:

Windows (WSL2):

{
  "mcpServers": {
    "bunkervm": {
      "command": "wsl",
      "args": ["-d", "Ubuntu", "--", "sudo", "python3", "-m", "bunkervm"]
    }
  }
}

Linux / macOS:

{
  "mcpServers": {
    "bunkervm": {
      "command": "sudo",
      "args": ["python3", "-m", "bunkervm"]
    }
  }
}

That's it. On first run, BunkerVM downloads a ~100MB pre-built micro-OS. After that, every launch boots a fresh VM in ~2 seconds.

What can it do?

Once connected, your AI agent gets these tools:

Tool	What it does
sandbox_exec	Run any shell command
sandbox_write_file	Create or edit files
sandbox_read_file	Read files
sandbox_list_dir	Browse directories
sandbox_status	Check VM health, CPU, RAM, disk
sandbox_reset	Wipe everything, start fresh

Example: Ask Claude to "write a Python script that fetches the top 10 Hacker News stories, then run it" — it writes the code inside the VM, executes it, and shows you the results. All isolated.

Why not Docker?

	BunkerVM	Docker
Isolation	Hardware (KVM) — separate kernel	Shared kernel
Escape risk	Near zero	Container escapes exist
Boot time	~2s	~0.5s
Self-hosted	Yes	Yes
Internet access	Optional	Yes
Setup	pip install	Dockerfile + build + run

BunkerVM runs each agent in a real virtual machine. If the agent goes rogue, it can't touch your host.

Requirements

• Linux with KVM support, or Windows with WSL2
• Python 3.10+
• ~100MB disk for the micro-OS bundle

For WSL2, enable nested virtualization in %USERPROFILE%\.wslconfig:

[wsl2]
nestedVirtualization=true

Works with any MCP client

BunkerVM speaks the Model Context Protocol. It works with:

• Claude Desktop
• LangGraph / LangChain
• Any MCP-compatible agent framework

# For LangGraph integration:
pip install bunkervm[langgraph]

See tests/test_langgraph.py for a working example.

How it works (you don't need to know this)

Under the hood

BunkerVM is a custom Alpine Linux micro-OS (~256MB) purpose-built for AI agent sandboxing:

Your AI  ──MCP──▶  bunkervm       ──vsock──▶  Firecracker MicroVM
                   (host)                      ┌──────────────┐
                                               │ Alpine Linux │
                                               │ Python 3     │
                                               │ gcc, git,    │
                                               │ curl, etc.   │
                                               │              │
                                               │ exec_agent   │
                                               └──────────────┘

• Firecracker — Amazon's micro-VM engine (same tech as AWS Lambda)
• vsock — Direct host↔VM communication, no networking needed
• TAP networking — Optional, gives the VM internet access
• exec_agent — HTTP server inside the VM that executes commands

The pre-built bundle (~100MB) includes Firecracker, a Linux kernel, and the rootfs. Downloaded once on first run to ~/.bunkervm/bundle/.

For contributors

Building from source

# Clone
git clone https://github.com/ashishgituser/bunkervm.git
cd bunkervm

# Build the micro-OS locally (needs Linux/WSL2 + sudo)
sudo bash build/setup-firecracker.sh    # Download Firecracker + kernel
sudo bash build/build-sandbox-rootfs.sh  # Build the 256MB rootfs

# Install in dev mode
pip install -e ".[dev]"

# Run
sudo python -m bunkervm

Files go into build/ locally. The bootstrap module auto-detects local builds.

License

AGPL-3.0 — Free for personal and open-source use. If you modify BunkerVM and offer it as a service, you must open-source your changes under the same license.

For commercial licensing, contact the author.