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 limitation:

• The bundled runtime is currently shim-based.
• doctor reports runtime capabilities, and current bundles report no real guest boot, no guest exec agent, and no guest networking.
• Until a real guest-capable bundle is installed, vm_exec runs in host_compat mode rather than guest_vsock.
• This means demo commands can exercise lifecycle/control-plane behavior, but they are not yet proof of command execution inside a real VM guest.

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

Current limitation:

• the pipeline is real, but the checked-in source artifacts in runtime_sources/ are still shim/placeholder inputs
• the real-source path depends on docker, outbound access to GitHub and Debian snapshot mirrors, and enough disk for kernel/rootfs builds
• replacing those inputs with real Firecracker binaries, a real kernel, and real rootfs images is what upgrades the packaged bundle from host_compat to true guest execution
• the next artifact-replacement steps are documented in runtime_sources/README.md

Run deterministic lifecycle demo

make demo

The demo creates a VM, starts it, runs a command, and returns structured output. If the runtime reports guest_vsock plus networking, it uses an internet probe. Otherwise it falls back to a local compatibility command and the result will report execution_mode=host_compat.

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.
• Host TAP/NAT setup is opt-in with:

PYRO_VM_ENABLE_NETWORK=1 make doctor

• Current limitation:
  • network metadata and host preflight exist
  • real in-guest outbound networking still depends on a non-shim runtime bundle with real guest boot and guest exec support

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

If the runtime is still shim-based, the summary will show execution_mode=host_compat. 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.