165 lines
4.7 KiB
Markdown
165 lines
4.7 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
make setup
|
|
```
|
|
|
|
## Build runtime bundle
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
make network-demo
|
|
```
|
|
|
|
## Runtime doctor
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
PYRO_VM_ENABLE_NETWORK=1 make 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.
|
|
- To validate real guest egress directly:
|
|
|
|
```bash
|
|
make runtime-network-check
|
|
```
|
|
|
|
## Run Ollama lifecycle demo
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
make ollama-demo OLLAMA_DEMO_FLAGS=-v
|
|
```
|
|
|
|
## Run MCP server
|
|
|
|
```bash
|
|
make run-server
|
|
```
|
|
|
|
## Quality checks
|
|
|
|
```bash
|
|
make check
|
|
```
|
|
|
|
Includes `ruff`, `mypy`, and `pytest` with coverage threshold.
|
|
|
|
## Pre-commit
|
|
|
|
```bash
|
|
make install-hooks
|
|
```
|
|
|
|
Hooks execute the same lint/type/test gates.
|