# 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
```