Metadata-Version: 2.4
Name: pyro-mcp
Version: 1.0.0
Summary: Curated Linux environments for ephemeral Firecracker-backed VM execution.
Project-URL: Homepage, https://git.thaloco.com/thaloco/pyro-mcp
Project-URL: Repository, https://git.thaloco.com/thaloco/pyro-mcp
Project-URL: Issues, https://git.thaloco.com/thaloco/pyro-mcp/issues
Author-email: Thales Maciel <thales@thalesmaciel.com>
License: MIT License
        
        Copyright (c) 2026 Thales Maciel
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.12
Requires-Dist: mcp>=1.26.0
Description-Content-Type: text/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 public Docker Hub repositories into a local
cache on first use or through `pyro env pull`.
End users do not need registry credentials to pull or run official environments.

## 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
export DOCKERHUB_USERNAME='your-dockerhub-username'
export DOCKERHUB_TOKEN='your-dockerhub-token'
make runtime-materialize
make runtime-publish-official-environments-oci
```

`make runtime-publish-environment-oci` auto-exports the OCI layout for the selected
environment if it is missing.
The publisher accepts either `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` or
`OCI_REGISTRY_USERNAME` and `OCI_REGISTRY_PASSWORD`.
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`.

For a local PyPI publish:

```bash
export TWINE_PASSWORD='pypi-...'
make pypi-publish
```

`make pypi-publish` defaults `TWINE_USERNAME` to `__token__`.
Set `PYPI_REPOSITORY_URL=https://test.pypi.org/legacy/` to publish to TestPyPI instead.
