thaloco/pyro-mcp
1
Fork 0
Code Pull requests Releases Packages Activity Actions

Add daily-loop prepare and readiness checks

Browse source 
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`.
This commit is contained in:
Thales Maciel 2026-03-13 21:17:59 -03:00
parent d0cf6d8f21
commit 663241d5d2
26 changed files with 1592 additions and 199 deletions
Download patch file Download diff file Expand all files Collapse all files

47
docs/install.md
View file

@ -46,29 +46,27 @@ 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 prepare 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 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 named chat mode
through `pyro host connect` or `pyro host print-config`.
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
uvx --from pyro-mcp pyro doctor --environment debian:12
```
Expected success signals:
@ -78,8 +76,11 @@ 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).
@ -139,7 +140,17 @@ 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
## 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:
@ -221,23 +232,24 @@ 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.
## 6. Go from zero to hero
## 7. Go from zero to hero
The intended user journey is:
1. validate the host with `pyro doctor`
2. pull `debian:12`
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. start with one use-case recipe from [use-cases/README.md](use-cases/README.md)
6. trust but verify with `make smoke-use-cases`
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).
## 7. Manual terminal workspace flow
## 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
@ -269,7 +281,7 @@ When you need deeper debugging or richer recipes, add:
private tokens
- `pyro workspace stop` plus `workspace disk *` for offline inspection
## 8. Trustworthy verification path
## 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:
@ -288,9 +300,8 @@ 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 doctor --environment debian:12
pyro prepare debian:12
pyro run debian:12 -- git --version
pyro mcp serve
```