Metadata-Version: 2.4
Name: bunkervm
Version: 0.2.4
Summary: Hardware-isolated Linux sandbox for AI agents — Firecracker MicroVM + MCP
Author: Ashish
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/ashishgituser/bunkervm
Project-URL: Documentation, https://github.com/ashishgituser/bunkervm#readme
Project-URL: Issues, https://github.com/ashishgituser/bunkervm/issues
Keywords: mcp,sandbox,firecracker,ai,agent,microvm,isolation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Emulators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: langgraph
Requires-Dist: langchain-openai>=0.1.0; extra == "langgraph"
Requires-Dist: langgraph>=0.1.0; extra == "langgraph"
Requires-Dist: langchain-core>=0.1.0; extra == "langgraph"
Requires-Dist: python-dotenv>=1.0.0; extra == "langgraph"
Dynamic: license-file

# 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):**
```json
{
  "mcpServers": {
    "bunkervm": {
      "command": "wsl",
      "args": ["-d", "Ubuntu", "--", "sudo", "python3", "-m", "bunkervm"]
    }
  }
}
```

**Linux / macOS:**
```json
{
  "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`:
```ini
[wsl2]
nestedVirtualization=true
```

## Works with any MCP client

BunkerVM speaks the [Model Context Protocol](https://modelcontextprotocol.io). It works with:
- Claude Desktop
- LangGraph / LangChain
- Any MCP-compatible agent framework

```bash
# For LangGraph integration:
pip install bunkervm[langgraph]
```

See [tests/test_langgraph.py](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

```bash
# 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.
