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

Add host bootstrap and repair helpers

Browse source 
Add a dedicated pyro host surface for supported chat hosts so Claude Code, Codex, and OpenCode users can connect or repair the canonical MCP setup without hand-writing raw commands or config edits.

Implement the shared host helper layer and wire it through the CLI with connect, print-config, doctor, and repair, all generated from the same canonical pyro mcp serve command shape and project-source flags. Update the docs, public contract, examples, changelog, and roadmap so the helper flow becomes the primary onramp while raw host-specific commands remain as reference material.

Harden the verification path that this milestone exposed: temp git repos in tests now disable commit signing, socket-based port tests skip cleanly when the sandbox forbids those primitives, and make test still uses multiple cores by default but caps xdist workers to a stable value so make check stays fast and deterministic here.

Validation:
- uv lock
- UV_OFFLINE=1 UV_CACHE_DIR=.uv-cache make check
- UV_OFFLINE=1 UV_CACHE_DIR=.uv-cache make dist-check
This commit is contained in:
Thales Maciel 2026-03-13 16:46:10 -03:00
parent 535efc6919
commit 899a6760c4
25 changed files with 1658 additions and 58 deletions
Download patch file Download diff file Expand all files Collapse all files

21
docs/first-run.md
View file

@ -27,7 +27,7 @@ Networking: tun=yes ip_forward=yes
```bash
$ uvx --from pyro-mcp pyro env list
Catalog version: 4.1.0
Catalog version: 4.2.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.
@ -93,9 +93,27 @@ $ uvx --from pyro-mcp pyro mcp serve --repo-url https://github.com/example/proje
## 6. Connect a chat host
Use the helper flow first:
```bash
$ uvx --from pyro-mcp pyro host connect claude-code
$ uvx --from pyro-mcp pyro host connect codex
$ uvx --from pyro-mcp pyro host print-config opencode
```
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:
```bash
$ uvx --from pyro-mcp pyro host connect claude-code
$ claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve
$ claude mcp list
```
@ -103,6 +121,7 @@ $ claude mcp list
Codex:
```bash
$ uvx --from pyro-mcp pyro host connect codex
$ codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve
$ codex mcp list
```

29
docs/install.md
View file

@ -62,7 +62,8 @@ 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 `pyro mcp serve`.
After that one-shot proof works, the intended next step is `pyro host connect`
or `pyro host print-config`.
## 1. Check the host
@ -92,7 +93,7 @@ uvx --from pyro-mcp pyro env list
Expected output:
```bash
Catalog version: 4.1.0
Catalog version: 4.2.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.
@ -140,6 +141,23 @@ deterministic structured result.
## 5. Connect a chat host
Use the helper flow first:
```bash
uvx --from pyro-mcp pyro host connect claude-code
uvx --from pyro-mcp pyro host connect codex
uvx --from pyro-mcp pyro host print-config opencode
```
If setup drifts later, inspect and repair it with:
```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
```
Bare `pyro mcp serve` now starts `workspace-core`. From a repo root, it also
auto-detects the current Git checkout so the first `workspace_create` can omit
`seed_path`.
@ -170,12 +188,14 @@ Copy-paste host-specific starts:
Claude Code:
```bash
pyro host connect claude-code
claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve
```
Codex:
```bash
pyro host connect codex
codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve
```
@ -195,8 +215,9 @@ The intended user journey is:
1. validate the host with `pyro doctor`
2. pull `debian:12`
3. prove guest execution with `pyro run debian:12 -- git --version`
4. connect Claude Code, Codex, or OpenCode with `pyro mcp serve` from a repo
root, or use `--project-path` / `--repo-url` when needed
4. connect Claude Code, Codex, or OpenCode with `pyro host connect ...` or
`pyro host print-config opencode`, then use raw `pyro mcp serve` only when
you need `--project-path` / `--repo-url`
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`

46
docs/integrations.md
View file

@ -38,8 +38,35 @@ 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 claude-code
pyro host connect codex
pyro host print-config opencode
pyro host doctor
pyro host repair opencode
```
These helpers wrap the same `pyro mcp serve` entrypoint, preserve the current
`workspace-core` default, and make it obvious how to repair drift later.
## Claude Code
Preferred:
```bash
pyro host connect claude-code
```
Repair:
```bash
pyro host repair claude-code
```
Package without install:
```bash
@ -66,6 +93,18 @@ Reference:
## Codex
Preferred:
```bash
pyro host connect codex
```
Repair:
```bash
pyro host repair codex
```
Package without install:
```bash
@ -92,6 +131,13 @@ Reference:
## 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)

11
docs/public-contract.md
View file

@ -94,6 +94,17 @@ Host-specific setup docs:
- [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.
## Chat-Facing Workspace Contract
`workspace-core` is the normal chat path. It exposes:

8
docs/roadmap/llm-chat-ergonomics.md
View file

@ -6,7 +6,7 @@ goal:
make the core agent-workspace use cases feel trivial from a chat-driven LLM
interface.
Current baseline is `4.1.0`:
Current baseline is `4.2.0`:
- `pyro mcp serve` is now the default product entrypoint
- `workspace-core` is now the default MCP profile
@ -80,7 +80,7 @@ capability gaps:
10. [`3.11.0` Host-Specific MCP Onramps](llm-chat-ergonomics/3.11.0-host-specific-mcp-onramps.md) - Done
11. [`4.0.0` Workspace-Core Default Profile](llm-chat-ergonomics/4.0.0-workspace-core-default-profile.md) - Done
12. [`4.1.0` Project-Aware Chat Startup](llm-chat-ergonomics/4.1.0-project-aware-chat-startup.md) - Done
13. [`4.2.0` Host Bootstrap And Repair](llm-chat-ergonomics/4.2.0-host-bootstrap-and-repair.md) - Planned
13. [`4.2.0` Host Bootstrap And Repair](llm-chat-ergonomics/4.2.0-host-bootstrap-and-repair.md) - Done
14. [`4.3.0` Reviewable Agent Output](llm-chat-ergonomics/4.3.0-reviewable-agent-output.md) - Planned
15. [`4.4.0` Opinionated Use-Case Modes](llm-chat-ergonomics/4.4.0-opinionated-use-case-modes.md) - Planned
16. [`4.5.0` Faster Daily Loops](llm-chat-ergonomics/4.5.0-faster-daily-loops.md) - Planned
@ -117,10 +117,12 @@ Completed so far:
- `4.1.0` made repo-root startup native for chat hosts, so bare `pyro mcp serve` can auto-detect
the current Git checkout and let the first `workspace_create` omit `seed_path`, with explicit
`--project-path` and `--repo-url` fallbacks when cwd is not the source of truth.
- `4.2.0` adds first-class host bootstrap and repair helpers so Claude Code,
Codex, and OpenCode users can connect or repair the supported chat-host path
without manually composing raw MCP commands or config edits.
Planned next:
- [`4.2.0` Host Bootstrap And Repair](llm-chat-ergonomics/4.2.0-host-bootstrap-and-repair.md)
- [`4.3.0` Reviewable Agent Output](llm-chat-ergonomics/4.3.0-reviewable-agent-output.md)
- [`4.4.0` Opinionated Use-Case Modes](llm-chat-ergonomics/4.4.0-opinionated-use-case-modes.md)
- [`4.5.0` Faster Daily Loops](llm-chat-ergonomics/4.5.0-faster-daily-loops.md)

2
docs/roadmap/llm-chat-ergonomics/4.2.0-host-bootstrap-and-repair.md
View file

@ -1,6 +1,6 @@
# `4.2.0` Host Bootstrap And Repair
Status: Planned
Status: Done
## Goal