pyro-mcp/docs/install.md

# Install

`pyro-mcp` is built for chat-based coding agents on Linux `x86_64` with KVM.
This document is intentionally biased toward that path.

`pyro-mcp` currently has no users. Expect breaking changes while the chat-host
flow is still being shaped.

## 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 either of these equivalent evaluator paths:

```bash
# Package without install
uvx --from pyro-mcp pyro doctor
uvx --from pyro-mcp pyro env list
uvx --from pyro-mcp pyro env pull debian:12
uvx --from pyro-mcp pyro run debian:12 -- git --version
```

```bash
# Already installed
pyro doctor
pyro env list
pyro env pull debian:12
pyro run debian:12 -- git --version
```

If you are running from a repo checkout instead, replace `pyro` with
`uv run pyro`.

After that one-shot proof works, the intended next step is `pyro mcp serve`.

## 1. Check the host

```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: 4.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.

Expected success signals:

```bash
[pull] phase=install environment=debian:12
[pull] phase=ready environment=debian:12
Pulled: debian:12
...
```

## 4. Run one command in a guest

```bash
uvx --from pyro-mcp pyro run debian:12 -- git --version
```

Expected success signals:

```bash
[run] phase=create environment=debian:12
[run] phase=start vm_id=...
[run] phase=execute vm_id=...
[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. Use `--json` if you need a
deterministic structured result.

## 5. Connect a chat host

Bare `pyro mcp serve` now starts `workspace-core`, which is the default
product path.

```bash
uvx --from pyro-mcp pyro mcp serve
```

Copy-paste host-specific starts:

- Claude Code setup: [claude_code_mcp.md](../examples/claude_code_mcp.md)
- Codex setup: [codex_mcp.md](../examples/codex_mcp.md)
- OpenCode config: [opencode_mcp_config.json](../examples/opencode_mcp_config.json)
- Generic MCP fallback: [mcp_client_config.md](../examples/mcp_client_config.md)

Claude Code:

```bash
claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve
```

Codex:

```bash
codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve
```

OpenCode uses the `mcp` / `type: "local"` config shape shown in
[opencode_mcp_config.json](../examples/opencode_mcp_config.json).

If `pyro-mcp` is already installed, replace `uvx --from pyro-mcp pyro` with
`pyro` in the same command or config shape.

Use `--profile workspace-full` only when the chat truly needs shells, services,
snapshots, secrets, network policy, or disk tools.

## 6. Go from zero to hero

The intended user journey is:

1. validate the host with `pyro doctor`
2. pull `debian:12`
3. prove guest execution with `pyro run debian:12 -- git --version`
4. connect Claude Code, Codex, or OpenCode with `pyro mcp serve`
5. start with one use-case recipe from [use-cases/README.md](use-cases/README.md)
6. trust but verify with `make smoke-use-cases`

If you want the shortest chat-first story, start with
[use-cases/repro-fix-loop.md](use-cases/repro-fix-loop.md).

## 7. Manual terminal workspace flow

If you want to inspect the workspace model directly from the terminal, use the
companion flow below. This is for understanding and debugging the chat-host
product, not the primary story.

```bash
uv tool install pyro-mcp
WORKSPACE_ID="$(pyro workspace create debian:12 --seed-path ./repo --name repro-fix --label issue=123 --id-only)"
pyro workspace list
pyro workspace update "$WORKSPACE_ID" --label owner=codex
pyro workspace sync push "$WORKSPACE_ID" ./changes
pyro workspace file read "$WORKSPACE_ID" note.txt --content-only
pyro workspace patch apply "$WORKSPACE_ID" --patch-file fix.patch
pyro workspace exec "$WORKSPACE_ID" -- cat note.txt
pyro workspace snapshot create "$WORKSPACE_ID" checkpoint
pyro workspace reset "$WORKSPACE_ID" --snapshot checkpoint
pyro workspace export "$WORKSPACE_ID" note.txt --output ./note.txt
pyro workspace delete "$WORKSPACE_ID"
```

When you need deeper debugging or richer recipes, add:

- `pyro workspace shell *` for interactive PTY state
- `pyro workspace service *` for long-running processes and readiness probes
- `pyro workspace create --network-policy egress+published-ports` plus
  `workspace service start --publish` for host-probed services
- `pyro workspace create --secret` and `--secret-file` when the sandbox needs
  private tokens
- `pyro workspace stop` plus `workspace disk *` for offline inspection

## 8. Trustworthy verification path

The five recipe docs in [use-cases/README.md](use-cases/README.md) are backed
by a real Firecracker smoke pack:

```bash
make smoke-use-cases
```

Treat that smoke pack as the trustworthy guest-backed verification path for the
advertised chat-host workflows.

## Installed CLI

If you already installed the package, the same path works with plain `pyro ...`:

```bash
uv tool install pyro-mcp
pyro --version
pyro doctor
pyro env list
pyro env pull debian:12
pyro run debian:12 -- git --version
pyro mcp serve
```

## Contributor clone

```bash
git lfs install
git clone <repo>
cd pyro
git lfs pull
make setup
```