# 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 prepare debian:12
uvx --from pyro-mcp pyro run debian:12 -- git --version
```

```bash
# Already installed
pyro doctor
pyro prepare 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 a warmed daily loop
plus a named chat mode through `pyro host connect` or `pyro host print-config`.

## 1. Check the host

```bash
uvx --from pyro-mcp pyro doctor --environment debian:12
```

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
Catalog version: 4.5.0
Capabilities: vm_boot=yes guest_exec=yes guest_network=yes
Networking: tun=yes ip_forward=yes
Daily loop: COLD (debian:12)
  Run: pyro prepare debian:12
```

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.4.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. Warm the daily loop

```bash
uvx --from pyro-mcp pyro prepare debian:12
```

That one command ensures the environment is installed, proves one guest-backed
create/exec/reset/delete loop, and records a warm manifest so the next
`pyro prepare debian:12` call can reuse it instead of repeating the full cycle.

## 6. Connect a chat host

Use the helper flow first:

```bash
uvx --from pyro-mcp pyro host connect codex --mode repro-fix
uvx --from pyro-mcp pyro host connect codex --mode inspect
uvx --from pyro-mcp pyro host connect claude-code --mode cold-start
uvx --from pyro-mcp pyro host connect claude-code --mode review-eval
uvx --from pyro-mcp pyro host print-config opencode --mode repro-fix
```

If setup drifts later, inspect and repair it with:

```bash
uvx --from pyro-mcp pyro host doctor
uvx --from pyro-mcp pyro host repair claude-code
uvx --from pyro-mcp pyro host repair codex
uvx --from pyro-mcp pyro host repair opencode
```

Use a named mode when one workflow already matches the job:

```bash
uvx --from pyro-mcp pyro mcp serve --mode repro-fix
uvx --from pyro-mcp pyro mcp serve --mode inspect
uvx --from pyro-mcp pyro mcp serve --mode cold-start
uvx --from pyro-mcp pyro mcp serve --mode review-eval
```

Use the generic no-mode path when the mode feels too narrow. Bare
`pyro mcp serve` still starts `workspace-core`. From a repo root, it also
auto-detects the current Git checkout so the first `workspace_create` can omit
`seed_path`.

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

If the host does not preserve the server working directory, use:

```bash
uvx --from pyro-mcp pyro mcp serve --project-path /abs/path/to/repo
```

If you are starting outside a local checkout, use a clean clone source:

```bash
uvx --from pyro-mcp pyro mcp serve --repo-url https://github.com/example/project.git
```

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 cold-start or review-eval:

```bash
pyro host connect claude-code --mode cold-start
claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode cold-start
```

Codex repro-fix or inspect:

```bash
pyro host connect codex --mode repro-fix
codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode repro-fix
```

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 the generic no-mode path when the named mode is too narrow. Move to
`--profile workspace-full` only when the chat truly needs shells, services,
snapshots, secrets, network policy, or disk tools.

## 7. Go from zero to hero

The intended user journey is:

1. validate the host with `pyro doctor --environment debian:12`
2. warm the machine with `pyro prepare debian:12`
3. prove guest execution with `pyro run debian:12 -- git --version`
4. connect Claude Code, Codex, or OpenCode with one named mode such as
   `pyro host connect codex --mode repro-fix`, then use raw
   `pyro mcp serve --mode ...` or the generic no-mode path when needed
5. use `workspace reset` as the normal retry step inside that warmed loop
6. start with one use-case recipe from [use-cases/README.md](use-cases/README.md)
7. 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).

## 8. 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 summary "$WORKSPACE_ID"
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

## 9. 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 --environment debian:12
pyro prepare 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
```