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:

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:

# 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

# 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 host connect or pyro host print-config.

1. Check the host

uvx --from pyro-mcp pyro doctor

Expected success signals:

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.

2. Inspect the catalog

uvx --from pyro-mcp pyro env list

Expected output:

Catalog version: 4.3.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

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 for the full host requirements.

Expected success signals:

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

4. Run one command in a guest

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

Expected success signals:

[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

Use the helper flow first:

uvx --from pyro-mcp pyro host connect claude-code
uvx --from pyro-mcp pyro host connect codex
uvx --from pyro-mcp pyro host print-config opencode

If setup drifts later, inspect and repair it with:

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

Bare pyro mcp serve now starts workspace-core. From a repo root, it also auto-detects the current Git checkout so the first workspace_create can omit seed_path.

uvx --from pyro-mcp pyro mcp serve

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

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:

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
• Codex setup: codex_mcp.md
• OpenCode config: opencode_mcp_config.json
• Generic MCP fallback: mcp_client_config.md

Claude Code:

pyro host connect claude-code
claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve

Codex:

pyro host connect codex
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.

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 host connect ... or pyro host print-config opencode, then use raw pyro mcp serve only when you need --project-path / --repo-url
5. start with one use-case recipe from 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.

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.

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

8. Trustworthy verification path

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

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

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

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