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`.
257 lines
5.3 KiB
Markdown
257 lines
5.3 KiB
Markdown
# Chat Host Integrations
|
|
|
|
This page documents the intended product path for `pyro-mcp`:
|
|
|
|
- validate the host with the CLI
|
|
- warm the daily loop with `pyro prepare debian:12`
|
|
- run `pyro mcp serve`
|
|
- connect a chat host
|
|
- let the agent work inside disposable workspaces
|
|
|
|
`pyro-mcp` currently has no users. Expect breaking changes while this chat-host
|
|
path is still being shaped.
|
|
|
|
Use this page after you have already validated the host and guest execution
|
|
through [install.md](install.md) or [first-run.md](first-run.md).
|
|
|
|
Recommended first commands before connecting a host:
|
|
|
|
```bash
|
|
pyro doctor --environment debian:12
|
|
pyro prepare debian:12
|
|
```
|
|
|
|
## Recommended Modes
|
|
|
|
Use a named mode when one workflow already matches the job:
|
|
|
|
```bash
|
|
pyro host connect codex --mode repro-fix
|
|
pyro host connect codex --mode inspect
|
|
pyro host connect claude-code --mode cold-start
|
|
pyro host connect claude-code --mode review-eval
|
|
```
|
|
|
|
The mode-backed raw server forms are:
|
|
|
|
```bash
|
|
pyro mcp serve --mode repro-fix
|
|
pyro mcp serve --mode inspect
|
|
pyro mcp serve --mode cold-start
|
|
pyro mcp serve --mode review-eval
|
|
```
|
|
|
|
Use the generic no-mode path only when the named mode feels too narrow.
|
|
|
|
## Generic Default
|
|
|
|
Bare `pyro mcp serve` starts `workspace-core`. From a repo root, it also
|
|
auto-detects the current Git checkout so the first `workspace_create` can omit
|
|
`seed_path`. That is the product path.
|
|
|
|
```bash
|
|
pyro mcp serve
|
|
```
|
|
|
|
If the host does not preserve cwd, fall back to:
|
|
|
|
```bash
|
|
pyro mcp serve --project-path /abs/path/to/repo
|
|
```
|
|
|
|
If you are outside a repo checkout entirely, start from a clean clone source:
|
|
|
|
```bash
|
|
pyro mcp serve --repo-url https://github.com/example/project.git
|
|
```
|
|
|
|
Use `--profile workspace-full` only when the chat truly needs shells, services,
|
|
snapshots, secrets, network policy, or disk tools.
|
|
|
|
## Helper First
|
|
|
|
Use the helper flow before the raw host CLI commands:
|
|
|
|
```bash
|
|
pyro host connect codex --mode repro-fix
|
|
pyro host connect codex --mode inspect
|
|
pyro host connect claude-code --mode cold-start
|
|
pyro host connect claude-code --mode review-eval
|
|
pyro host print-config opencode --mode repro-fix
|
|
pyro host doctor
|
|
pyro host repair opencode
|
|
```
|
|
|
|
These helpers wrap the same `pyro mcp serve` entrypoint, make named modes the
|
|
first user-facing story, and still leave the generic no-mode path available
|
|
when a mode is too narrow.
|
|
|
|
## Claude Code
|
|
|
|
Preferred:
|
|
|
|
```bash
|
|
pyro host connect claude-code --mode cold-start
|
|
```
|
|
|
|
Repair:
|
|
|
|
```bash
|
|
pyro host repair claude-code
|
|
```
|
|
|
|
Package without install:
|
|
|
|
```bash
|
|
claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode cold-start
|
|
claude mcp list
|
|
```
|
|
|
|
If Claude Code launches the server from an unexpected cwd, use:
|
|
|
|
```bash
|
|
claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode cold-start --project-path /abs/path/to/repo
|
|
```
|
|
|
|
Already installed:
|
|
|
|
```bash
|
|
claude mcp add pyro -- pyro mcp serve
|
|
claude mcp list
|
|
```
|
|
|
|
Reference:
|
|
|
|
- [claude_code_mcp.md](../examples/claude_code_mcp.md)
|
|
|
|
## Codex
|
|
|
|
Preferred:
|
|
|
|
```bash
|
|
pyro host connect codex --mode repro-fix
|
|
```
|
|
|
|
Repair:
|
|
|
|
```bash
|
|
pyro host repair codex
|
|
```
|
|
|
|
Package without install:
|
|
|
|
```bash
|
|
codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode repro-fix
|
|
codex mcp list
|
|
```
|
|
|
|
If Codex launches the server from an unexpected cwd, use:
|
|
|
|
```bash
|
|
codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode repro-fix --project-path /abs/path/to/repo
|
|
```
|
|
|
|
Already installed:
|
|
|
|
```bash
|
|
codex mcp add pyro -- pyro mcp serve
|
|
codex mcp list
|
|
```
|
|
|
|
Reference:
|
|
|
|
- [codex_mcp.md](../examples/codex_mcp.md)
|
|
|
|
## OpenCode
|
|
|
|
Preferred:
|
|
|
|
```bash
|
|
pyro host print-config opencode
|
|
pyro host repair opencode
|
|
```
|
|
|
|
Use the local MCP config shape from:
|
|
|
|
- [opencode_mcp_config.json](../examples/opencode_mcp_config.json)
|
|
|
|
Minimal `opencode.json` snippet:
|
|
|
|
```json
|
|
{
|
|
"mcp": {
|
|
"pyro": {
|
|
"type": "local",
|
|
"enabled": true,
|
|
"command": ["uvx", "--from", "pyro-mcp", "pyro", "mcp", "serve", "--mode", "repro-fix"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
If `pyro-mcp` is already installed, replace `uvx --from pyro-mcp pyro` with
|
|
`pyro` in the same config shape.
|
|
|
|
If OpenCode launches the server from an unexpected cwd, add
|
|
`"--project-path", "/abs/path/to/repo"` after `"serve"` in the same command
|
|
array.
|
|
|
|
## Generic MCP Fallback
|
|
|
|
Use this only when the host expects a plain `mcpServers` JSON config, when the
|
|
named modes are too narrow, and when it does not already have a dedicated
|
|
example in the repo:
|
|
|
|
- [mcp_client_config.md](../examples/mcp_client_config.md)
|
|
|
|
Generic `mcpServers` shape:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"pyro": {
|
|
"command": "uvx",
|
|
"args": ["--from", "pyro-mcp", "pyro", "mcp", "serve"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## When To Use `workspace-full`
|
|
|
|
Stay on bare `pyro mcp serve` unless the chat host truly needs:
|
|
|
|
- persistent PTY shell sessions
|
|
- long-running services and readiness probes
|
|
- secrets
|
|
- guest networking and published ports
|
|
- stopped-workspace disk inspection or raw ext4 export
|
|
|
|
When that is necessary:
|
|
|
|
```bash
|
|
pyro mcp serve --profile workspace-full
|
|
```
|
|
|
|
## Recipe-Backed Workflows
|
|
|
|
Once the host is connected, move to the five real workflows in
|
|
[use-cases/README.md](use-cases/README.md):
|
|
|
|
- cold-start repo validation
|
|
- repro plus fix loops
|
|
- parallel isolated workspaces
|
|
- unsafe or untrusted code inspection
|
|
- review and evaluation workflows
|
|
|
|
Validate the whole story with:
|
|
|
|
```bash
|
|
make smoke-use-cases
|
|
```
|
|
|
|
For the machine-warmup plus reset/retry path specifically:
|
|
|
|
```bash
|
|
make smoke-daily-loop
|
|
```
|