159 lines
3.5 KiB
Markdown
159 lines
3.5 KiB
Markdown
# Install
|
|
|
|
## Support Matrix
|
|
|
|
Supported today:
|
|
|
|
- Linux x86_64
|
|
- Python 3.12+
|
|
- `uv`
|
|
- `/dev/kvm`
|
|
|
|
Optional for outbound guest networking:
|
|
|
|
- `ip`
|
|
- `nft` or `iptables`
|
|
- privilege to create TAP devices and configure NAT
|
|
|
|
Not supported today:
|
|
|
|
- macOS
|
|
- Windows
|
|
- Linux hosts without working KVM at `/dev/kvm`
|
|
|
|
If you do not already have `uv`, install it first:
|
|
|
|
```bash
|
|
python -m pip install uv
|
|
```
|
|
|
|
Use these command forms consistently:
|
|
|
|
- published package without install: `uvx --from pyro-mcp pyro ...`
|
|
- installed package: `pyro ...`
|
|
- source checkout: `uv run pyro ...`
|
|
|
|
## Fastest Evaluation Path
|
|
|
|
Use the package directly without a manual install:
|
|
|
|
If you are running from a repo checkout instead, replace `uvx --from pyro-mcp pyro` with `uv run pyro`.
|
|
|
|
### 1. Check the host first
|
|
|
|
```bash
|
|
uvx --from pyro-mcp pyro doctor
|
|
```
|
|
|
|
Expected success signals:
|
|
|
|
```bash
|
|
Platform: linux-x86_64
|
|
Runtime: PASS
|
|
KVM: exists=yes readable=yes writable=yes
|
|
Environment cache: /home/you/.cache/pyro-mcp/environments
|
|
Capabilities: vm_boot=yes guest_exec=yes guest_network=yes
|
|
Networking: tun=yes ip_forward=yes
|
|
```
|
|
|
|
If `Runtime: FAIL`, stop here and use [troubleshooting.md](troubleshooting.md).
|
|
|
|
### 2. Inspect the catalog
|
|
|
|
```bash
|
|
uvx --from pyro-mcp pyro env list
|
|
```
|
|
|
|
Expected output:
|
|
|
|
```bash
|
|
Catalog version: 2.0.0
|
|
debian:12 [installed|not installed] Debian 12 environment with Git preinstalled for common agent workflows.
|
|
debian:12-base [installed|not installed] Minimal Debian 12 environment for shell and core Unix tooling.
|
|
debian:12-build [installed|not installed] Debian 12 environment with Git and common build tools preinstalled.
|
|
```
|
|
|
|
### 3. Pull the default environment
|
|
|
|
```bash
|
|
uvx --from pyro-mcp pyro env pull debian:12
|
|
```
|
|
|
|
The first pull downloads an OCI environment from public Docker Hub, requires outbound HTTPS
|
|
access to `registry-1.docker.io`, and needs local cache space for the guest image. See
|
|
[host-requirements.md](host-requirements.md) for the full host requirements.
|
|
|
|
### 4. Run one command in a guest
|
|
|
|
```bash
|
|
uvx --from pyro-mcp pyro run debian:12 -- git --version
|
|
```
|
|
|
|
Expected success signals:
|
|
|
|
```bash
|
|
[run] environment=debian:12 execution_mode=guest_vsock exit_code=0 duration_ms=...
|
|
git version ...
|
|
```
|
|
|
|
The guest command output and the `[run] ...` summary are written to different streams, so they
|
|
may appear in either order in terminals or capture tools. Use `--json` if you need a
|
|
deterministic structured result.
|
|
|
|
If guest execution is unavailable, the command fails unless you explicitly pass
|
|
`--allow-host-compat`.
|
|
|
|
## 5. Optional demo proof point
|
|
|
|
```bash
|
|
uvx --from pyro-mcp pyro demo
|
|
```
|
|
|
|
`pyro demo` proves the one-shot create/start/exec/delete VM lifecycle works end to end.
|
|
|
|
Example output:
|
|
|
|
```json
|
|
{
|
|
"cleanup": {
|
|
"deleted": true,
|
|
"reason": "post_exec_cleanup",
|
|
"vm_id": "..."
|
|
},
|
|
"command": "git --version",
|
|
"environment": "debian:12",
|
|
"execution_mode": "guest_vsock",
|
|
"exit_code": 0,
|
|
"stdout": "git version ...\n"
|
|
}
|
|
```
|
|
|
|
For a fuller copy-pasteable transcript, see [first-run.md](first-run.md).
|
|
When you are done evaluating and want to remove stale cached environments, run `pyro env prune`.
|
|
|
|
## Installed CLI
|
|
|
|
```bash
|
|
uv tool install pyro-mcp
|
|
pyro --version
|
|
pyro doctor
|
|
pyro env list
|
|
pyro env pull debian:12
|
|
pyro run debian:12 -- git --version
|
|
```
|
|
|
|
After the CLI path works, you can move on to:
|
|
|
|
- MCP: `pyro mcp serve`
|
|
- Python SDK: `from pyro_mcp import Pyro`
|
|
- Demos: `pyro demo` or `pyro demo --network`
|
|
|
|
## Contributor Clone
|
|
|
|
```bash
|
|
git lfs install
|
|
git clone <repo>
|
|
cd pyro
|
|
git lfs pull
|
|
make setup
|
|
```
|