Thales Maciel
84a7e18d4d
Complete the 2.6.0 workspace milestone by adding explicit host-out export and immutable-baseline diff across the CLI, Python SDK, and MCP server. Capture a baseline archive at workspace creation, export live /workspace paths through the guest agent, and compute structured whole-workspace diffs on the host without affecting command logs or shell state. The docs, roadmap, bundled guest agent, and workspace example now reflect the new create -> sync -> diff -> export workflow. Validation: uv lock, UV_CACHE_DIR=.uv-cache make check, UV_CACHE_DIR=.uv-cache make dist-check, and a real guest-backed Firecracker smoke covering workspace create, sync push, diff, export, and delete.
152 lines
6.2 KiB
Markdown
152 lines
6.2 KiB
Markdown
# First Run Transcript
|
|
|
|
This is the intended evaluator 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`.
|
|
|
|
## 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: 2.6.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
|
|
Install manifest: /home/you/.cache/pyro-mcp/environments/linux-x86_64/debian_12-1.0.0/environment.json
|
|
Kernel image: /home/you/.cache/pyro-mcp/environments/linux-x86_64/debian_12-1.0.0/vmlinux
|
|
Rootfs image: /home/you/.cache/pyro-mcp/environments/linux-x86_64/debian_12-1.0.0/rootfs.ext4
|
|
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. Optional next steps
|
|
|
|
```bash
|
|
$ uvx --from pyro-mcp pyro demo
|
|
$ uvx --from pyro-mcp pyro workspace create debian:12 --seed-path ./repo
|
|
$ uvx --from pyro-mcp pyro workspace sync push WORKSPACE_ID ./changes
|
|
$ uvx --from pyro-mcp pyro workspace diff WORKSPACE_ID
|
|
$ uvx --from pyro-mcp pyro workspace export WORKSPACE_ID note.txt --output ./note.txt
|
|
$ uvx --from pyro-mcp pyro workspace shell open WORKSPACE_ID
|
|
$ uvx --from pyro-mcp pyro mcp serve
|
|
```
|
|
|
|
`pyro demo` proves the one-shot create/start/exec/delete VM lifecycle works end to end.
|
|
|
|
When you need repeated commands in one sandbox, switch to `pyro workspace ...`:
|
|
|
|
```bash
|
|
$ uvx --from pyro-mcp pyro workspace create debian:12 --seed-path ./repo
|
|
Workspace ID: ...
|
|
Environment: debian:12
|
|
State: started
|
|
Workspace: /workspace
|
|
Workspace seed: directory from ...
|
|
Execution mode: guest_vsock
|
|
Resources: 1 vCPU / 1024 MiB
|
|
Command count: 0
|
|
|
|
$ uvx --from pyro-mcp pyro workspace sync push WORKSPACE_ID ./changes --dest src
|
|
[workspace-sync] workspace_id=... mode=directory source=... destination=/workspace/src entry_count=... bytes_written=... execution_mode=guest_vsock
|
|
|
|
$ uvx --from pyro-mcp pyro workspace exec WORKSPACE_ID -- cat src/note.txt
|
|
hello from synced workspace
|
|
[workspace-exec] workspace_id=... sequence=1 cwd=/workspace execution_mode=guest_vsock exit_code=0 duration_ms=...
|
|
|
|
$ uvx --from pyro-mcp pyro workspace diff WORKSPACE_ID
|
|
[workspace-diff] workspace_id=... total=... added=... modified=... deleted=... type_changed=... text_patched=... non_text=...
|
|
--- a/src/note.txt
|
|
+++ b/src/note.txt
|
|
@@ ...
|
|
|
|
$ uvx --from pyro-mcp pyro workspace export WORKSPACE_ID src/note.txt --output ./note.txt
|
|
[workspace-export] workspace_id=... workspace_path=/workspace/src/note.txt output_path=... artifact_type=file entry_count=... bytes_written=... execution_mode=guest_vsock
|
|
|
|
$ uvx --from pyro-mcp pyro workspace shell open WORKSPACE_ID
|
|
[workspace-shell-open] workspace_id=... shell_id=... state=running cwd=/workspace cols=120 rows=30 execution_mode=guest_vsock
|
|
|
|
$ uvx --from pyro-mcp pyro workspace shell write WORKSPACE_ID SHELL_ID --input 'pwd'
|
|
[workspace-shell-write] workspace_id=... shell_id=... state=running cwd=/workspace cols=120 rows=30 execution_mode=guest_vsock
|
|
|
|
$ uvx --from pyro-mcp pyro workspace shell read WORKSPACE_ID SHELL_ID
|
|
/workspace
|
|
[workspace-shell-read] workspace_id=... shell_id=... state=running cursor=0 next_cursor=... truncated=False execution_mode=guest_vsock
|
|
```
|
|
|
|
Use `--seed-path` when the workspace should start from a host directory or a local
|
|
`.tar` / `.tar.gz` / `.tgz` archive instead of an empty `/workspace`. Use
|
|
`pyro workspace sync push` when you need to import later host-side changes into a started
|
|
workspace. Sync is non-atomic in `2.6.0`; if it fails partway through, delete and recreate the
|
|
workspace. Use `pyro workspace diff` to compare the current `/workspace` tree to its immutable
|
|
create-time baseline, and `pyro workspace export` to copy one changed file or directory back to
|
|
the host. Use `pyro workspace exec` for one-shot commands and `pyro workspace shell *` when you
|
|
need a persistent interactive PTY session in that same workspace.
|
|
|
|
Example output:
|
|
|
|
```json
|
|
{
|
|
"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"
|
|
}
|
|
```
|
|
|
|
When you are done evaluating and want to remove stale cached environments, run `pyro env prune`.
|
|
|
|
If `pyro doctor` reports `Runtime: FAIL`, or if the `pyro run` summary does not show
|
|
`execution_mode=guest_vsock`, stop and use [troubleshooting.md](troubleshooting.md).
|