pyro-mcp/README.md

pyro-mcp

pyro-mcp runs commands inside ephemeral Firecracker microVMs using curated Linux environments such as debian:12.

It exposes the same runtime in three public forms:

• the pyro CLI
• the Python SDK via from pyro_mcp import Pyro
• an MCP server so LLM clients can call VM tools directly

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.

Official Environments

Current official environments in the shipped catalog:

• debian:12
• debian:12-base
• debian:12-build

The package ships the embedded Firecracker runtime and a package-controlled environment catalog. Official environments are pulled as OCI artifacts from Docker Hub into a local cache on first use or through pyro env pull.

CLI

List available environments:

pyro env list

Prefetch one environment:

pyro env pull debian:12

Run one command in an ephemeral VM:

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

Run with outbound internet enabled:

pyro run debian:12 --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 llama3.2:3b
pyro demo ollama

Python SDK

from pyro_mcp import Pyro

pyro = Pyro()
result = pyro.run_in_vm(
    environment="debian:12",
    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(
    environment="debian:12",
    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"])

Environment management is also available through the SDK:

from pyro_mcp import Pyro

pyro = Pyro()
print(pyro.list_environments())
print(pyro.inspect_environment("debian:12"))

MCP Tools

Primary agent-facing tool:

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

Advanced lifecycle tools:

• vm_list_environments()
• vm_create(environment, 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()

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

Runtime

The package ships an embedded Linux x86_64 runtime payload with:

• Firecracker
• Jailer
• guest agent
• runtime manifest and diagnostics

No system Firecracker installation is required. pyro installs curated environments into a local cache and reports their status through pyro env inspect and pyro doctor.

Contributor Workflow

For work inside this repository:

make help
make setup
make check
make dist-check

Contributor runtime source artifacts are still maintained under src/pyro_mcp/runtime_bundle/ and runtime_sources/.

Official environment publication is automated through .github/workflows/publish-environments.yml. For a local publish against Docker Hub:

make runtime-materialize
OCI_REGISTRY_USERNAME="$DOCKERHUB_USERNAME" OCI_REGISTRY_PASSWORD="$DOCKERHUB_TOKEN" \
  make runtime-publish-official-environments-oci

make runtime-publish-environment-oci auto-exports the OCI layout for the selected environment if it is missing. Docker Hub uploads are chunked by default for large rootfs layers; if you need to tune a slow link, use PYRO_OCI_UPLOAD_TIMEOUT_SECONDS, PYRO_OCI_UPLOAD_CHUNK_SIZE_BYTES, and PYRO_OCI_REQUEST_TIMEOUT_SECONDS.