204 lines
4.9 KiB
Markdown
204 lines
4.9 KiB
Markdown
# 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 GHCR 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 dry run against GHCR-compatible credentials:
|
|
|
|
```bash
|
|
make runtime-materialize
|
|
OCI_REGISTRY_USERNAME="$GITHUB_USER" OCI_REGISTRY_PASSWORD="$GITHUB_TOKEN" \
|
|
make runtime-publish-official-environments-oci
|
|
```
|