# 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

```bash
make setup
```

## Run deterministic lifecycle demo

```bash
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

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

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