pyro-mcp/README.md

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.

Start Here

• Install: docs/install.md
• Host requirements: docs/host-requirements.md
• Integration targets: docs/integrations.md
• Public contract: docs/public-contract.md
• Troubleshooting: docs/troubleshooting.md

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.

Check the installed CLI version:

pyro --version

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

Integration Examples

• Python one-shot SDK example: examples/python_run.py
• Python lifecycle example: examples/python_lifecycle.py
• MCP client config example: examples/mcp_client_config.md
• Claude Desktop MCP config: examples/claude_desktop_mcp_config.json
• Cursor MCP config: examples/cursor_mcp_config.json
• OpenAI Responses API example: examples/openai_responses_vm_run.py
• LangChain wrapper example: examples/langchain_vm_run.py
• Agent-ready vm_run example: examples/agent_vm_run.py

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"])

The recommended agent-facing default is still one-shot execution through run_in_vm(...) / vm_run. Use lifecycle methods only when the agent needs VM state to persist across multiple calls.

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
make dist-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.