diff --git a/README.md b/README.md index fdfd24e..5a804e0 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,10 @@ `pyro-mcp` runs commands inside ephemeral Firecracker microVMs using curated Linux environments such as `debian:12`. +[![PyPI version](https://img.shields.io/pypi/v/pyro-mcp.svg)](https://pypi.org/project/pyro-mcp/) + +This is for coding agents, MCP clients, and developers who want isolated command execution in ephemeral microVMs. + It exposes the same runtime in three public forms: - the `pyro` CLI @@ -12,6 +16,7 @@ It exposes the same runtime in three public forms: - Install: [docs/install.md](docs/install.md) - First run transcript: [docs/first-run.md](docs/first-run.md) +- Terminal walkthrough GIF: [docs/assets/first-run.gif](docs/assets/first-run.gif) - PyPI package: [pypi.org/project/pyro-mcp](https://pypi.org/project/pyro-mcp/) - Host requirements: [docs/host-requirements.md](docs/host-requirements.md) - Integration targets: [docs/integrations.md](docs/integrations.md) @@ -63,6 +68,8 @@ uv run pyro doctor Use the package directly without a manual install: +If you are running from a repo checkout instead, replace `uvx --from pyro-mcp pyro` with `uv run pyro`. + ### 1. Check the host ```bash @@ -127,7 +134,29 @@ uvx --from pyro-mcp pyro demo uvx --from pyro-mcp pyro demo --network ``` +`pyro demo` proves the one-shot create/start/exec/delete VM lifecycle works end to end. + +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 you prefer a fuller copy-pasteable transcript, see [docs/first-run.md](docs/first-run.md). +The walkthrough GIF above was rendered from [docs/assets/first-run.tape](docs/assets/first-run.tape) using [scripts/render_tape.sh](scripts/render_tape.sh). ## Public Interfaces diff --git a/docs/assets/first-run.gif b/docs/assets/first-run.gif new file mode 100644 index 0000000..3883cc8 Binary files /dev/null and b/docs/assets/first-run.gif differ diff --git a/docs/assets/first-run.tape b/docs/assets/first-run.tape new file mode 100644 index 0000000..d5574c7 --- /dev/null +++ b/docs/assets/first-run.tape @@ -0,0 +1,50 @@ +Output docs/assets/first-run.gif + +Require uv + +Set Shell "zsh" +Set FontSize 18 +Set Width 1200 +Set Height 820 +Set Theme "Dracula" +Set TypingSpeed 35ms +Set Padding 24 +Set WindowBar Colorful + +Hide +Type "cd /home/thales/projects/personal/pyro" +Enter +Type "export UV_CACHE_DIR=.uv-cache" +Enter +Show + +Type "printf '\\n# Check host support from the repo checkout\\n'" +Enter +Sleep 800ms +Type "uv run pyro doctor" +Enter +Sleep 2200ms + +Type "printf '\\n# Inspect and pull the default environment\\n'" +Enter +Sleep 800ms +Type "uv run pyro env list" +Enter +Sleep 1800ms +Type "uv run pyro env pull debian:12" +Enter +Sleep 1800ms + +Type "printf '\\n# Run one command in an isolated guest\\n'" +Enter +Sleep 800ms +Type "uv run pyro run debian:12 -- git --version" +Enter +Sleep 2200ms + +Type "printf '\\n# Prove the one-shot VM lifecycle demo\\n'" +Enter +Sleep 800ms +Type "uv run pyro demo" +Enter +Sleep 2600ms diff --git a/docs/first-run.md b/docs/first-run.md index 8cb8c11..4d2f947 100644 --- a/docs/first-run.md +++ b/docs/first-run.md @@ -67,5 +67,26 @@ $ uvx --from pyro-mcp pyro demo $ uvx --from pyro-mcp pyro mcp serve ``` +`pyro demo` proves the one-shot create/start/exec/delete VM lifecycle works end to end. + +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). diff --git a/docs/install.md b/docs/install.md index 280d73f..f3e5627 100644 --- a/docs/install.md +++ b/docs/install.md @@ -37,6 +37,8 @@ Use these command forms consistently: Use the package directly without a manual install: +If you are running from a repo checkout instead, replace `uvx --from pyro-mcp pyro` with `uv run pyro`. + ### 1. Check the host first ```bash @@ -101,7 +103,33 @@ deterministic structured result. If guest execution is unavailable, the command fails unless you explicitly pass `--allow-host-compat`. +## 5. Optional demo proof point + +```bash +uvx --from pyro-mcp pyro demo +``` + +`pyro demo` proves the one-shot create/start/exec/delete VM lifecycle works end to end. + +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" +} +``` + For a fuller copy-pasteable transcript, see [first-run.md](first-run.md). +When you are done evaluating and want to remove stale cached environments, run `pyro env prune`. ## Installed CLI diff --git a/scripts/render_tape.sh b/scripts/render_tape.sh new file mode 100755 index 0000000..08b4b6e --- /dev/null +++ b/scripts/render_tape.sh @@ -0,0 +1,25 @@ +#!/usr/bin/env bash +set -euo pipefail + +if [ "$#" -lt 1 ] || [ "$#" -gt 2 ]; then + printf 'Usage: %s [output-file]\n' "$0" >&2 + exit 1 +fi + +if ! command -v vhs >/dev/null 2>&1; then + printf '%s\n' 'vhs is required to render terminal recordings.' >&2 + exit 1 +fi + +ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +TAPE_FILE="$1" +OUTPUT_FILE="${2:-}" + +cd "$ROOT_DIR" +vhs validate "$TAPE_FILE" + +if [ -n "$OUTPUT_FILE" ]; then + vhs -o "$OUTPUT_FILE" "$TAPE_FILE" +else + vhs "$TAPE_FILE" +fi