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](docs/install.md)
- Host requirements: [docs/host-requirements.md](docs/host-requirements.md)
- Integration targets: [docs/integrations.md](docs/integrations.md)
- Public contract: [docs/public-contract.md](docs/public-contract.md)
- Troubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md)

## Public UX

Primary install/run path:

```bash
uvx --from pyro-mcp pyro mcp serve
```

Installed package path:

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

```bash
pyro env list
```

Prefetch one environment:

```bash
pyro env pull debian:12
```

Run one command in an ephemeral VM:

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

Run with outbound internet enabled:

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

```bash
pyro doctor
```

Run the deterministic demo:

```bash
pyro demo
pyro demo --network
```

Run the Ollama demo:

```bash
ollama serve
ollama pull llama3.2:3b
pyro demo ollama
```

## Python SDK

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

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

```python
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](examples/python_run.py)
- Python lifecycle example: [examples/python_lifecycle.py](examples/python_lifecycle.py)
- MCP client config example: [examples/mcp_client_config.md](examples/mcp_client_config.md)
- Claude Desktop MCP config: [examples/claude_desktop_mcp_config.json](examples/claude_desktop_mcp_config.json)
- Cursor MCP config: [examples/cursor_mcp_config.json](examples/cursor_mcp_config.json)
- OpenAI Responses API example: [examples/openai_responses_vm_run.py](examples/openai_responses_vm_run.py)
- LangChain wrapper example: [examples/langchain_vm_run.py](examples/langchain_vm_run.py)
- Agent-ready `vm_run` example: [examples/agent_vm_run.py](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:

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

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