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`.
232 lines
7.2 KiB
Markdown
232 lines
7.2 KiB
Markdown
# First Run Transcript
|
|
|
|
This is the intended evaluator-to-chat-host path for a first successful run on
|
|
a supported host.
|
|
|
|
Copy the commands as-is. Paths and timing values will differ on your machine.
|
|
The same sequence works with an installed `pyro` binary by dropping the
|
|
`uvx --from pyro-mcp` prefix. If you are running from a source checkout
|
|
instead of the published package, replace `pyro` with `uv run pyro`.
|
|
|
|
`pyro-mcp` currently has no users. Expect breaking changes while the chat-host
|
|
path is still being shaped.
|
|
|
|
## 1. Verify the host
|
|
|
|
```bash
|
|
$ uvx --from pyro-mcp pyro doctor --environment debian:12
|
|
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
|
|
```
|
|
|
|
## 2. Inspect the catalog
|
|
|
|
```bash
|
|
$ uvx --from pyro-mcp pyro env list
|
|
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
|
|
|
|
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.
|
|
|
|
```bash
|
|
$ uvx --from pyro-mcp pyro env pull debian:12
|
|
[pull] phase=install environment=debian:12
|
|
[pull] phase=ready environment=debian:12
|
|
Pulled: debian:12
|
|
Version: 1.0.0
|
|
Distribution: debian 12
|
|
Installed: yes
|
|
Cache dir: /home/you/.cache/pyro-mcp/environments
|
|
Default packages: bash, coreutils, git
|
|
Install dir: /home/you/.cache/pyro-mcp/environments/linux-x86_64/debian_12-1.0.0
|
|
OCI source: registry-1.docker.io/thalesmaciel/pyro-environment-debian-12:1.0.0
|
|
```
|
|
|
|
## 4. Run one command in a guest
|
|
|
|
```bash
|
|
$ uvx --from pyro-mcp pyro run debian:12 -- git --version
|
|
[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 in terminals or capture tools. Use
|
|
`--json` if you need a deterministic structured result.
|
|
|
|
## 5. Start the MCP server
|
|
|
|
Warm the daily loop first so the host is already ready for repeated create and
|
|
reset cycles:
|
|
|
|
```bash
|
|
$ uvx --from pyro-mcp pyro prepare debian:12
|
|
Prepare: debian:12
|
|
Daily loop: WARM
|
|
Result: prepared network_prepared=no
|
|
```
|
|
|
|
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:
|
|
|
|
```bash
|
|
$ uvx --from pyro-mcp pyro mcp serve --project-path /abs/path/to/repo
|
|
```
|
|
|
|
If you are outside a local checkout:
|
|
|
|
```bash
|
|
$ uvx --from pyro-mcp pyro mcp serve --repo-url https://github.com/example/project.git
|
|
```
|
|
|
|
## 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:
|
|
|
|
```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
|
|
```
|
|
|
|
Claude Code cold-start or review-eval:
|
|
|
|
```bash
|
|
$ uvx --from pyro-mcp pyro host connect claude-code --mode cold-start
|
|
$ claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode cold-start
|
|
$ claude mcp list
|
|
```
|
|
|
|
Codex repro-fix or inspect:
|
|
|
|
```bash
|
|
$ uvx --from pyro-mcp pyro host connect codex --mode repro-fix
|
|
$ codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode repro-fix
|
|
$ codex mcp list
|
|
```
|
|
|
|
OpenCode uses the local config shape shown in:
|
|
|
|
- [opencode_mcp_config.json](../examples/opencode_mcp_config.json)
|
|
|
|
Other host-specific references:
|
|
|
|
- [claude_code_mcp.md](../examples/claude_code_mcp.md)
|
|
- [codex_mcp.md](../examples/codex_mcp.md)
|
|
- [mcp_client_config.md](../examples/mcp_client_config.md)
|
|
|
|
## 7. Continue into a real workflow
|
|
|
|
Once the host is connected, move to one of the five recipe docs in
|
|
[use-cases/README.md](use-cases/README.md).
|
|
|
|
The shortest chat-first mode and story is:
|
|
|
|
- [use-cases/repro-fix-loop.md](use-cases/repro-fix-loop.md)
|
|
|
|
If you want terminal-level visibility into what the agent gets, use the manual
|
|
workspace flow below:
|
|
|
|
```bash
|
|
$ export WORKSPACE_ID="$(uvx --from pyro-mcp pyro workspace create debian:12 --seed-path ./repo --name repro-fix --label issue=123 --id-only)"
|
|
$ uvx --from pyro-mcp pyro workspace list
|
|
$ uvx --from pyro-mcp pyro workspace sync push "$WORKSPACE_ID" ./changes
|
|
$ uvx --from pyro-mcp pyro workspace file read "$WORKSPACE_ID" note.txt --content-only
|
|
$ uvx --from pyro-mcp pyro workspace patch apply "$WORKSPACE_ID" --patch-file fix.patch
|
|
$ uvx --from pyro-mcp pyro workspace exec "$WORKSPACE_ID" -- cat note.txt
|
|
$ uvx --from pyro-mcp pyro workspace summary "$WORKSPACE_ID"
|
|
$ uvx --from pyro-mcp pyro workspace snapshot create "$WORKSPACE_ID" checkpoint
|
|
$ uvx --from pyro-mcp pyro workspace reset "$WORKSPACE_ID" --snapshot checkpoint
|
|
$ uvx --from pyro-mcp pyro workspace export "$WORKSPACE_ID" note.txt --output ./note.txt
|
|
$ uvx --from pyro-mcp pyro workspace delete "$WORKSPACE_ID"
|
|
```
|
|
|
|
Move to the generic no-mode path when the named mode is too narrow. Move to
|
|
`--profile workspace-full` only when the chat really needs shells, services,
|
|
snapshots, secrets, network policy, or disk tools.
|
|
|
|
## 8. Trust the smoke pack
|
|
|
|
The repo now treats the full smoke pack as the trustworthy guest-backed
|
|
verification path for the advertised workflows:
|
|
|
|
```bash
|
|
$ make smoke-use-cases
|
|
```
|
|
|
|
That runner creates real guest-backed workspaces, exercises all five documented
|
|
stories, exports concrete results where relevant, and cleans up on both success
|
|
and failure.
|
|
|
|
For the machine-level warmup plus retry story specifically:
|
|
|
|
```bash
|
|
$ make smoke-daily-loop
|
|
```
|
|
|
|
## 9. Optional one-shot demo
|
|
|
|
```bash
|
|
$ uvx --from pyro-mcp pyro demo
|
|
{
|
|
"cleanup": {
|
|
"deleted": true,
|
|
"reason": "post_exec_cleanup",
|
|
"vm_id": "..."
|
|
},
|
|
"command": "git --version",
|
|
"environment": "debian:12",
|
|
"execution_mode": "guest_vsock",
|
|
"exit_code": 0,
|
|
"stdout": "git version ...\n"
|
|
}
|
|
```
|
|
|
|
`pyro demo` proves the one-shot create/start/exec/delete VM lifecycle works end
|
|
to end.
|