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`.
192 lines
6.3 KiB
Markdown
192 lines
6.3 KiB
Markdown
# Public Contract
|
|
|
|
This document describes the chat way to use `pyro-mcp` in `4.x`.
|
|
|
|
`pyro-mcp` currently has no users. Expect breaking changes while this chat-host
|
|
path is still being shaped.
|
|
|
|
This document is intentionally biased. It describes the path users are meant to
|
|
follow today:
|
|
|
|
- prove the host with the terminal companion commands
|
|
- serve disposable workspaces over MCP
|
|
- connect Claude Code, Codex, or OpenCode
|
|
- use the recipe-backed workflows
|
|
|
|
This page does not try to document every building block in the repo. It
|
|
documents the chat-host path the project is actively shaping.
|
|
|
|
## Package Identity
|
|
|
|
- distribution name: `pyro-mcp`
|
|
- public executable: `pyro`
|
|
- primary product entrypoint: `pyro mcp serve`
|
|
|
|
`pyro-mcp` is a disposable MCP workspace for chat-based coding agents on Linux
|
|
`x86_64` KVM hosts.
|
|
|
|
## Supported Product Path
|
|
|
|
The intended user journey is:
|
|
|
|
1. `pyro doctor`
|
|
2. `pyro prepare debian:12`
|
|
3. `pyro run debian:12 -- git --version`
|
|
4. `pyro mcp serve`
|
|
5. connect Claude Code, Codex, or OpenCode
|
|
6. use `workspace reset` as the normal retry step
|
|
7. run one of the documented recipe-backed workflows
|
|
8. validate the whole story with `make smoke-use-cases`
|
|
|
|
## Evaluator CLI
|
|
|
|
These terminal commands are the documented companion path for the chat-host
|
|
product:
|
|
|
|
- `pyro doctor`
|
|
- `pyro prepare`
|
|
- `pyro env list`
|
|
- `pyro env pull`
|
|
- `pyro run`
|
|
- `pyro demo`
|
|
|
|
What to expect from that path:
|
|
|
|
- `pyro run <environment> -- <command>` defaults to `1 vCPU / 1024 MiB`
|
|
- `pyro run` fails if guest boot or guest exec is unavailable unless
|
|
`--allow-host-compat` is set
|
|
- `pyro run`, `pyro env list`, `pyro env pull`, `pyro env inspect`,
|
|
`pyro env prune`, `pyro doctor`, and `pyro prepare` are human-readable by
|
|
default and return structured JSON with `--json`
|
|
- the first official environment pull downloads from public Docker Hub into the
|
|
local environment cache
|
|
- `pyro prepare debian:12` proves the warmed daily loop with one throwaway
|
|
workspace create, exec, reset, and delete cycle
|
|
- `pyro demo` proves the one-shot create/start/exec/delete VM lifecycle end to
|
|
end
|
|
|
|
These commands exist to validate and debug the chat-host path. They are not the
|
|
main product destination.
|
|
|
|
## MCP Entry Point
|
|
|
|
The product entrypoint is:
|
|
|
|
```bash
|
|
pyro mcp serve
|
|
```
|
|
|
|
What to expect:
|
|
|
|
- named modes are now the first chat-host story:
|
|
- `pyro mcp serve --mode repro-fix`
|
|
- `pyro mcp serve --mode inspect`
|
|
- `pyro mcp serve --mode cold-start`
|
|
- `pyro mcp serve --mode review-eval`
|
|
- bare `pyro mcp serve` remains the generic no-mode path and starts
|
|
`workspace-core`
|
|
- from a repo root, bare `pyro mcp serve` also auto-detects the current Git
|
|
checkout so `workspace_create` can omit `seed_path`
|
|
- `pyro mcp serve --profile workspace-full` explicitly opts into the larger
|
|
tool surface
|
|
- `pyro mcp serve --profile vm-run` exposes the smallest one-shot-only surface
|
|
- `pyro mcp serve --project-path /abs/path/to/repo` is the fallback when the
|
|
host does not preserve cwd
|
|
- `pyro mcp serve --repo-url ... [--repo-ref ...]` starts from a clean clone
|
|
source instead of a local checkout
|
|
|
|
Host-specific setup docs:
|
|
|
|
- [claude_code_mcp.md](../examples/claude_code_mcp.md)
|
|
- [codex_mcp.md](../examples/codex_mcp.md)
|
|
- [opencode_mcp_config.json](../examples/opencode_mcp_config.json)
|
|
- [mcp_client_config.md](../examples/mcp_client_config.md)
|
|
|
|
The chat-host bootstrap helper surface is:
|
|
|
|
- `pyro host connect claude-code`
|
|
- `pyro host connect codex`
|
|
- `pyro host print-config opencode`
|
|
- `pyro host doctor`
|
|
- `pyro host repair HOST`
|
|
|
|
These helpers wrap the same `pyro mcp serve` entrypoint and are the preferred
|
|
setup and repair path for supported hosts.
|
|
|
|
## Named Modes
|
|
|
|
The supported named modes are:
|
|
|
|
| Mode | Intended workflow | Key tools |
|
|
| --- | --- | --- |
|
|
| `repro-fix` | reproduce, patch, rerun, diff, export, reset | file ops, patch, diff, export, reset, summary |
|
|
| `inspect` | inspect suspicious or unfamiliar code with the smallest persistent surface | file list/read, exec, export, summary |
|
|
| `cold-start` | validate a fresh repo and keep services alive long enough to prove readiness | exec, export, reset, summary, service tools |
|
|
| `review-eval` | interactive review, checkpointing, shell-driven evaluation, and export | shell tools, snapshot tools, diff/export, summary |
|
|
|
|
Use the generic no-mode path when one of those named modes feels too narrow for
|
|
the job.
|
|
|
|
## Generic Workspace Contract
|
|
|
|
`workspace-core` is the normal chat path. It exposes:
|
|
|
|
- `vm_run`
|
|
- `workspace_create`
|
|
- `workspace_list`
|
|
- `workspace_update`
|
|
- `workspace_status`
|
|
- `workspace_sync_push`
|
|
- `workspace_exec`
|
|
- `workspace_logs`
|
|
- `workspace_summary`
|
|
- `workspace_file_list`
|
|
- `workspace_file_read`
|
|
- `workspace_file_write`
|
|
- `workspace_patch_apply`
|
|
- `workspace_diff`
|
|
- `workspace_export`
|
|
- `workspace_reset`
|
|
- `workspace_delete`
|
|
|
|
That is enough for the normal persistent editing loop:
|
|
|
|
- create one workspace, often without `seed_path` when the server already has a
|
|
project source
|
|
- sync or seed repo content
|
|
- inspect and edit files without shell quoting
|
|
- run commands repeatedly in one sandbox
|
|
- review the current session in one concise summary
|
|
- diff and export results
|
|
- reset and retry
|
|
- delete the workspace when the task is done
|
|
|
|
Move to `workspace-full` only when the chat truly needs:
|
|
|
|
- persistent PTY shell sessions
|
|
- long-running services and readiness probes
|
|
- secrets
|
|
- guest networking and published ports
|
|
- stopped-workspace disk inspection
|
|
|
|
## Recipe-Backed Workflows
|
|
|
|
The documented product workflows are:
|
|
|
|
| Workflow | Recommended mode | Doc |
|
|
| --- | --- | --- |
|
|
| Cold-start repo validation | `cold-start` | [use-cases/cold-start-repo-validation.md](use-cases/cold-start-repo-validation.md) |
|
|
| Repro plus fix loop | `repro-fix` | [use-cases/repro-fix-loop.md](use-cases/repro-fix-loop.md) |
|
|
| Parallel isolated workspaces | `repro-fix` | [use-cases/parallel-workspaces.md](use-cases/parallel-workspaces.md) |
|
|
| Unsafe or untrusted code inspection | `inspect` | [use-cases/untrusted-inspection.md](use-cases/untrusted-inspection.md) |
|
|
| Review and evaluation workflows | `review-eval` | [use-cases/review-eval-workflows.md](use-cases/review-eval-workflows.md) |
|
|
|
|
Treat this smoke pack as the trustworthy guest-backed verification path for the
|
|
advertised product:
|
|
|
|
```bash
|
|
make smoke-use-cases
|
|
```
|
|
|
|
The chat-host MCP path above is the thing the docs are intentionally shaping
|
|
around.
|