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.
5.5 KiB
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
$ 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
$ 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 for the
full host requirements.
$ 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
$ 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:
$ uvx --from pyro-mcp pyro mcp serve
If the host does not preserve the server working directory:
$ uvx --from pyro-mcp pyro mcp serve --project-path /abs/path/to/repo
If you are outside a local checkout:
$ uvx --from pyro-mcp pyro mcp serve --repo-url https://github.com/example/project.git
6. Connect a chat host
Claude Code:
$ claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve
$ claude mcp list
Codex:
$ codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve
$ codex mcp list
OpenCode uses the local config shape shown in:
Other host-specific references:
7. Continue into a real workflow
Once the host is connected, move to one of the five recipe docs in use-cases/README.md.
The shortest chat-first story is:
If you want terminal-level visibility into what the agent gets, use the manual workspace flow below:
$ 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:
$ 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
$ 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.