pyro-mcp

pyro-mcp is a Firecracker-backed sandbox for coding agents.

It exposes the same runtime in two public forms:

• a pyro CLI
• a Python SDK via from pyro_mcp import Pyro

It also ships an MCP server so LLM clients can use the same VM runtime through tools.

Public UX

Primary install/run path:

uvx --from pyro-mcp pyro mcp serve

Installed package path:

pyro mcp serve

The public user-facing interface is pyro and Pyro. Makefile targets are contributor conveniences for this repository and are not the primary product UX.

Repository Storage

This repository uses Git LFS for the packaged runtime images under src/pyro_mcp/runtime_bundle/.

Fresh contributor setup:

git lfs install
git clone <repo>
cd pyro
git lfs pull
make setup

The large files tracked through LFS are:

• src/pyro_mcp/runtime_bundle/**/rootfs.ext4
• src/pyro_mcp/runtime_bundle/**/vmlinux

If you are working from an older clone created before the LFS migration, reclone or realign your branch to the rewritten history before doing more work.

Capabilities

• Firecracker microVM execution with bundled runtime artifacts
• standard profiles:
  • debian-base
  • debian-git
  • debian-build
• high-level one-shot execution via vm_run / Pyro.run_in_vm(...)
• low-level lifecycle control when needed:
  • vm_create
  • vm_start
  • vm_exec
  • vm_stop
  • vm_delete
  • vm_status
  • vm_network_info
  • vm_reap_expired
• outbound guest networking with explicit opt-in

Requirements

• Linux host
• /dev/kvm
• Python 3.12+
• host privilege for TAP/NAT setup when using guest networking

The current implementation uses sudo -n for ip, nft, and iptables when networked runs are requested.

CLI

Start the MCP server:

pyro mcp serve

Run one command in an ephemeral VM:

pyro run --profile debian-git --vcpu-count 1 --mem-mib 1024 -- git --version

Run with outbound internet enabled:

pyro run --profile debian-git --vcpu-count 1 --mem-mib 1024 --network -- \
  "git clone --depth 1 https://github.com/octocat/Hello-World.git hello-world && git -C hello-world rev-parse --is-inside-work-tree"

Show runtime and host diagnostics:

pyro doctor

Run the deterministic demo:

pyro demo
pyro demo --network

Run the Ollama demo:

ollama serve
ollama pull llama:3.2-3b
pyro demo ollama

Verbose Ollama logs:

pyro demo ollama -v

Python SDK

from pyro_mcp import Pyro

pyro = Pyro()
result = pyro.run_in_vm(
    profile="debian-git",
    command="git --version",
    vcpu_count=1,
    mem_mib=1024,
    timeout_seconds=30,
    network=False,
)
print(result["stdout"])

Lower-level lifecycle control remains available:

from pyro_mcp import Pyro

pyro = Pyro()
created = pyro.create_vm(
    profile="debian-git",
    vcpu_count=1,
    mem_mib=1024,
    ttl_seconds=600,
    network=True,
)
vm_id = created["vm_id"]
pyro.start_vm(vm_id)
result = pyro.exec_vm(vm_id, command="git --version", timeout_seconds=30)
print(result["stdout"])

MCP Tools

Primary agent-facing tool:

• vm_run(profile, command, vcpu_count, mem_mib, timeout_seconds=30, ttl_seconds=600, network=false)

Advanced lifecycle tools:

• vm_list_profiles()
• vm_create(profile, vcpu_count, mem_mib, ttl_seconds=600, network=false)
• vm_start(vm_id)
• vm_exec(vm_id, command, timeout_seconds=30)
• vm_stop(vm_id)
• vm_delete(vm_id)
• vm_status(vm_id)
• vm_network_info(vm_id)
• vm_reap_expired()

Runtime

The package ships a bundled Linux x86_64 runtime payload with:

• Firecracker
• Jailer
• guest kernel
• guest agent
• profile rootfs images

No system Firecracker installation is required.

Runtime diagnostics:

pyro doctor

The doctor report includes:

• runtime integrity
• component versions
• capability flags
• KVM availability
• host networking prerequisites

Contributor Workflow

For work inside this repository:

make help
make setup
make check

Runtime build and validation helpers remain available through make, including:

• make runtime-bundle
• make runtime-materialize
• make runtime-boot-check
• make runtime-network-check

Space cleanup after runtime work:

rm -rf build
git lfs prune

Recreating .venv/ is also a straightforward way to reclaim local disk if needed.