Thales Maciel 663241d5d2 Add daily-loop prepare and readiness checks

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

2026-03-13 21:17:59 -03:00

9 KiB

Raw Blame History

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

# 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

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

Expected success signals:

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.

2. Inspect the catalog

uvx --from pyro-mcp pyro env list

Expected output:

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

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

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:

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:

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:

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.

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

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:

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.

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:

validate the host with pyro doctor --environment debian:12
warm the machine with pyro prepare debian:12
prove guest execution with pyro run debian:12 -- git --version
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
use workspace reset as the normal retry step inside that warmed loop
start with one use-case recipe from use-cases/README.md
trust but verify with make smoke-use-cases

If you want the shortest chat-first story, start with 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.

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 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 --environment debian:12
pyro prepare 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

9 KiB Raw Blame History

Install

Support Matrix

Fastest Evaluation Path

1. Check the host

2. Inspect the catalog

3. Pull the default environment

4. Run one command in a guest

5. Warm the daily loop

6. Connect a chat host

7. Go from zero to hero

8. Manual terminal workspace flow

9. Trustworthy verification path

Installed CLI

Contributor clone

9 KiB

Raw Blame History