thaloco/pyro-mcp
1
Fork 0
Code Pull requests Releases Packages Activity Actions
pyro-mcp/docs/integrations.md
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

5.3 KiB
Raw Permalink Blame History

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 or first-run.md.

Recommended first commands before connecting a host:

pyro doctor --environment debian:12
pyro prepare debian:12

Recommended Modes

Use a named mode when one workflow already matches the job:

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:

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.

pyro mcp serve

If the host does not preserve cwd, fall back to:

pyro mcp serve --project-path /abs/path/to/repo

If you are outside a repo checkout entirely, start from a clean clone source:

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:

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:

pyro host connect claude-code --mode cold-start

Repair:

pyro host repair claude-code

Package without install:

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:

claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode cold-start --project-path /abs/path/to/repo

Already installed:

claude mcp add pyro -- pyro mcp serve
claude mcp list

Reference:

Codex

Preferred:

pyro host connect codex --mode repro-fix

Repair:

pyro host repair codex

Package without install:

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:

codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode repro-fix --project-path /abs/path/to/repo

Already installed:

codex mcp add pyro -- pyro mcp serve
codex mcp list

Reference:

OpenCode

Preferred:

pyro host print-config opencode
pyro host repair opencode

Use the local MCP config shape from:

Minimal opencode.json snippet:

{
  "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:

Generic mcpServers shape:

{
  "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:

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:

  • 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:

make smoke-use-cases

For the machine-warmup plus reset/retry path specifically:

make smoke-daily-loop