Thales Maciel
535efc6919
Make repo-root chat startup native by letting MCP servers carry a default project source for workspace creation. When a chat host starts from a Git checkout, workspace_create can now omit seed_path and inherit the server startup source; explicit --project-path and clean-clone --repo-url/--repo-ref paths are supported as fallbacks. Add project startup resolution and materialization, surface origin_kind/origin_ref in workspace_seed, update chat-host docs and the repro/fix smoke to use project-aware workspace creation, and switch dist-check to uv run pyro so verification stays stable after uv reinstalls. Validated with uv lock, focused startup/server/CLI pytest coverage, UV_CACHE_DIR=.uv-cache make check, UV_CACHE_DIR=.uv-cache make dist-check, and real guest-backed smokes for both explicit project_path and bare repo-root auto-detection.
180 lines
5.5 KiB
Markdown
180 lines
5.5 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
|
|
Platform: linux-x86_64
|
|
Runtime: PASS
|
|
KVM: exists=yes readable=yes writable=yes
|
|
Environment cache: /home/you/.cache/pyro-mcp/environments
|
|
Capabilities: vm_boot=yes guest_exec=yes guest_network=yes
|
|
Networking: tun=yes ip_forward=yes
|
|
```
|
|
|
|
## 2. Inspect the catalog
|
|
|
|
```bash
|
|
$ uvx --from pyro-mcp pyro env list
|
|
Catalog version: 4.1.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
|
|
|
|
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`:
|
|
|
|
```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
|
|
|
|
Claude Code:
|
|
|
|
```bash
|
|
$ claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve
|
|
$ claude mcp list
|
|
```
|
|
|
|
Codex:
|
|
|
|
```bash
|
|
$ codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve
|
|
$ 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 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 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 `--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.
|
|
|
|
## 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.
|