Thales Maciel
663241d5d2
Make the local chat-host loop explicit and cheap so users can warm the machine once instead of rediscovering environment and guest setup on every session. Add cache-backed daily-loop manifests plus the new `pyro prepare` flow, extend `pyro doctor --environment` with warm/cold/stale readiness reporting, and add `make smoke-daily-loop` to prove the warmed repro-fix reset path end to end. Also fix `python -m pyro_mcp.cli` to invoke `main()` so the new smoke and `dist-check` actually exercise the CLI module, and update the docs/roadmap to present `doctor -> prepare -> connect host -> reset` as the recommended daily path. Validation: `uv lock`, `UV_OFFLINE=1 UV_CACHE_DIR=.uv-cache make check`, `UV_OFFLINE=1 UV_CACHE_DIR=.uv-cache make dist-check`, and `UV_OFFLINE=1 UV_CACHE_DIR=.uv-cache make smoke-daily-loop`.
317 lines
9 KiB
Markdown
317 lines
9 KiB
Markdown
# 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
|
|
```
|