thaloco/pyro-mcp
1
Fork 0
Code Pull requests Releases Packages Activity Actions

Refactor public API around environments

Browse source
This commit is contained in:
Thales Maciel 2026-03-08 16:02:02 -03:00
parent 57dae52cc2
commit 5d5243df23
41 changed files with 1301 additions and 459 deletions
Download patch file Download diff file Expand all files Collapse all files

179
README.md
View file

@ -1,21 +1,20 @@
# pyro-mcp
`pyro-mcp` is a Firecracker-backed sandbox for coding agents.
`pyro-mcp` runs commands inside ephemeral Firecracker microVMs using curated Linux environments such as `debian:12`.
It exposes the same runtime in two public forms:
It exposes the same runtime in three public forms:
- a `pyro` CLI
- a Python SDK via `from pyro_mcp import Pyro`
It also ships an MCP server so LLM clients can use the same VM runtime through tools.
- 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](/home/thales/projects/personal/pyro/docs/install.md)
- Host requirements: [docs/host-requirements.md](/home/thales/projects/personal/pyro/docs/host-requirements.md)
- Integration targets: [docs/integrations.md](/home/thales/projects/personal/pyro/docs/integrations.md)
- Public contract: [docs/public-contract.md](/home/thales/projects/personal/pyro/docs/public-contract.md)
- Troubleshooting: [docs/troubleshooting.md](/home/thales/projects/personal/pyro/docs/troubleshooting.md)
- 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
@ -34,80 +33,41 @@ 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.
Check the installed CLI version:
## Official Environments
```bash
pyro --version
```
Current curated environments in this repository:
## Repository Storage
- `debian:12`
- `debian:12-base`
- `debian:12-build`
This repository uses Git LFS for the packaged runtime images under
`src/pyro_mcp/runtime_bundle/`.
Fresh contributor setup:
```bash
git lfs install
git clone <repo>
cd pyro
git lfs pull
make setup
```
The large files tracked through LFS are:
- `src/pyro_mcp/runtime_bundle/**/rootfs.ext4`
- `src/pyro_mcp/runtime_bundle/**/vmlinux`
If you are working from an older clone created before the LFS migration, reclone or realign your branch to the rewritten history before doing more work.
## Capabilities
- Firecracker microVM execution with bundled runtime artifacts
- standard profiles:
- `debian-base`
- `debian-git`
- `debian-build`
- high-level one-shot execution via `vm_run` / `Pyro.run_in_vm(...)`
- low-level lifecycle control when needed:
- `vm_create`
- `vm_start`
- `vm_exec`
- `vm_stop`
- `vm_delete`
- `vm_status`
- `vm_network_info`
- `vm_reap_expired`
- outbound guest networking with explicit opt-in
## Requirements
- Linux host
- `/dev/kvm`
- Python 3.12+
- host privilege for TAP/NAT setup when using guest networking
The current implementation uses `sudo -n` for `ip`, `nft`, and `iptables` when networked runs are requested.
The package ships the embedded Firecracker runtime and a package-controlled environment catalog.
Environment artifacts are installed into a local cache on first use or through `pyro env pull`.
## CLI
Start the MCP server:
List available environments:
```bash
pyro mcp serve
pyro env list
```
Prefetch one environment:
```bash
pyro env pull debian:12
```
Run one command in an ephemeral VM:
```bash
pyro run --profile debian-git --vcpu-count 1 --mem-mib 1024 -- git --version
pyro run debian:12 --vcpu-count 1 --mem-mib 1024 -- git --version
```
Run with outbound internet enabled:
```bash
pyro run --profile debian-git --vcpu-count 1 --mem-mib 1024 --network -- \
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"
```
@ -132,23 +92,6 @@ ollama pull llama:3.2-3b
pyro demo ollama
```
Verbose Ollama logs:
```bash
pyro demo ollama -v
```
## Integration Examples
- Python one-shot SDK example: [examples/python_run.py](/home/thales/projects/personal/pyro/examples/python_run.py)
- Python lifecycle example: [examples/python_lifecycle.py](/home/thales/projects/personal/pyro/examples/python_lifecycle.py)
- MCP client config example: [examples/mcp_client_config.md](/home/thales/projects/personal/pyro/examples/mcp_client_config.md)
- Claude Desktop MCP config: [examples/claude_desktop_mcp_config.json](/home/thales/projects/personal/pyro/examples/claude_desktop_mcp_config.json)
- Cursor MCP config: [examples/cursor_mcp_config.json](/home/thales/projects/personal/pyro/examples/cursor_mcp_config.json)
- OpenAI Responses API example: [examples/openai_responses_vm_run.py](/home/thales/projects/personal/pyro/examples/openai_responses_vm_run.py)
- LangChain wrapper example: [examples/langchain_vm_run.py](/home/thales/projects/personal/pyro/examples/langchain_vm_run.py)
- Agent-ready `vm_run` example: [examples/agent_vm_run.py](/home/thales/projects/personal/pyro/examples/agent_vm_run.py)
## Python SDK
```python
@ -156,7 +99,7 @@ from pyro_mcp import Pyro
pyro = Pyro()
result = pyro.run_in_vm(
profile="debian-git",
environment="debian:12",
command="git --version",
vcpu_count=1,
mem_mib=1024,
@ -173,7 +116,7 @@ from pyro_mcp import Pyro
pyro = Pyro()
created = pyro.create_vm(
profile="debian-git",
environment="debian:12",
vcpu_count=1,
mem_mib=1024,
ttl_seconds=600,
@ -185,19 +128,26 @@ result = pyro.exec_vm(vm_id, command="git --version", timeout_seconds=30)
print(result["stdout"])
```
The recommended agent-facing default is still one-shot execution through `run_in_vm(...)` / `vm_run`.
Use lifecycle methods only when the agent needs VM state to persist across multiple calls.
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(profile, command, vcpu_count, mem_mib, timeout_seconds=30, ttl_seconds=600, network=false)`
- `vm_run(environment, command, vcpu_count, mem_mib, timeout_seconds=30, ttl_seconds=600, network=false)`
Advanced lifecycle tools:
- `vm_list_profiles()`
- `vm_create(profile, vcpu_count, mem_mib, ttl_seconds=600, network=false)`
- `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)`
@ -206,31 +156,28 @@ Advanced lifecycle tools:
- `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 a bundled Linux x86_64 runtime payload with:
The package ships an embedded Linux x86_64 runtime payload with:
- Firecracker
- Jailer
- guest kernel
- guest agent
- profile rootfs images
- runtime manifest and diagnostics
No system Firecracker installation is required.
Runtime diagnostics:
```bash
pyro doctor
```
The doctor report includes:
- runtime integrity
- component versions
- capability flags
- KVM availability
- host networking prerequisites
`pyro` installs curated environments into a local cache and reports their status through `pyro env inspect` and `pyro doctor`.
## Contributor Workflow
@ -243,18 +190,4 @@ make check
make dist-check
```
Runtime build and validation helpers remain available through `make`, including:
- `make runtime-bundle`
- `make runtime-materialize`
- `make runtime-boot-check`
- `make runtime-network-check`
Space cleanup after runtime work:
```bash
rm -rf build
git lfs prune
```
Recreating `.venv/` is also a straightforward way to reclaim local disk if needed.
Contributor runtime source artifacts are still maintained under `src/pyro_mcp/runtime_bundle/` and `runtime_sources/`.