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.

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