pyro-mcp/README.md

pyro-mcp

pyro-mcp is an MCP-compatible tool package for running ephemeral development environments with a VM lifecycle API.

v0.1.0 Capabilities

• Split lifecycle tools for coding agents: vm_list_profiles, vm_create, vm_start, vm_exec, vm_stop, vm_delete, vm_status, vm_network_info, vm_reap_expired.
• Standard environment profiles:
• debian-base: minimal Debian shell/core Unix tools.
• debian-git: Debian base with Git preinstalled.
• debian-build: Debian Git profile with common build tooling.
• Explicit sizing contract for agents (vcpu_count, mem_mib) with guardrails.
• Strict ephemerality for command execution (vm_exec auto-deletes VM on completion).
• Ollama demo that asks an LLM to clone a small public Git repository through lifecycle tools.

Runtime

The package includes a bundled Linux x86_64 runtime payload:

• Firecracker binary
• Jailer binary
• Profile artifacts for debian-base, debian-git, and debian-build

No system Firecracker installation is required for basic usage.

Current status:

• The bundled runtime is real, not shim-based.
• doctor reports real guest capability flags for VM boot, guest exec, and guest networking.
• vm_exec now runs in guest_vsock mode when the VM is started from the bundled runtime.
• Networking still requires host privileges for TAP/NAT setup; see the networking section below.

Host requirements still apply:

• Linux host
• /dev/kvm available for full virtualization mode

Requirements

• Python 3.12+
• uv
• Optional for Ollama demo: local Ollama server and llama:3.2-3b model.

Setup

make setup

Build runtime bundle

make runtime-bundle

This builds the packaged runtime bundle from runtime_sources/ and syncs the result into src/pyro_mcp/runtime_bundle/. For real artifacts, first materialize upstream sources into build/runtime_sources/.

Available staged targets:

• make runtime-binaries
• make runtime-kernel
• make runtime-rootfs
• make runtime-agent
• make runtime-validate
• make runtime-manifest
• make runtime-sync
• make runtime-clean

Available real-runtime targets:

• make runtime-fetch-binaries
• make runtime-build-kernel-real
• make runtime-build-rootfs-real
• make runtime-materialize
• make runtime-boot-check
• make runtime-network-check

Notes:

• the real-source path depends on docker, outbound access to GitHub and Debian snapshot mirrors, and enough disk for kernel/rootfs builds
• make runtime-boot-check validates that the bundled runtime can boot a real microVM
• make runtime-network-check validates outbound internet access from inside the guest by cloning https://github.com/octocat/Hello-World.git

Run deterministic lifecycle demo

make demo

The demo creates a VM, starts it, runs a command, and returns structured output. If the VM was started with networking enabled, it uses an internet probe. Otherwise it runs git --version.

To run the deterministic demo with guest networking enabled:

make network-demo

Runtime doctor

make doctor

This prints bundled runtime paths, profile availability, checksum validation status, runtime capability flags, KVM host checks, and host networking diagnostics.

Networking

• Host-side network allocation and diagnostics are implemented.
• The MCP server exposes vm_network_info for per-VM network metadata.
• Primary network-enabled entrypoints:

make network-demo
make ollama-demo

• Network setup requires host privilege to manage TAP/NAT state.
• The current implementation auto-uses sudo -n for ip, nft, and iptables commands when available.
• Manual opt-in for other commands is still available with:

PYRO_VM_ENABLE_NETWORK=1 make demo

• To validate real guest egress directly:

make runtime-network-check

Run Ollama lifecycle demo

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

Defaults are configured in Makefile. The demo streams lifecycle progress logs and ends with a short text summary. make ollama-demo now enables guest networking by default. The command it asks the model to run is a small public repository clone:

rm -rf hello-world && git clone --depth 1 https://github.com/octocat/Hello-World.git hello-world >/dev/null && git -C hello-world rev-parse --is-inside-work-tree

By default it omits log values; to include prompt content, tool args, and tool results use:

make ollama-demo OLLAMA_DEMO_FLAGS=-v

Run MCP server

make run-server

Quality checks

make check

Includes ruff, mypy, and pytest with coverage threshold.

Pre-commit

make install-hooks

Hooks execute the same lint/type/test gates.