From 227983a877e4777222183948204d424e1d018c33 Mon Sep 17 00:00:00 2001 From: Thales Maciel Date: Sat, 7 Mar 2026 17:14:52 -0300 Subject: [PATCH] Document Git LFS runtime bundle workflow --- AGENTS.md | 4 ++++ README.md | 31 +++++++++++++++++++++++++++++++ runtime_sources/README.md | 1 + 3 files changed, 36 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index a6ed039..3c481d7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,10 +9,12 @@ This repository ships `pyro-mcp`, an MCP-compatible package for ephemeral VM lif ## Development Workflow - Use `uv` for all Python environment and command execution. +- Install Git LFS before cloning or materializing the packaged runtime bundle: `git lfs install`. - Run `make setup` after cloning. - Run `make check` before opening a PR. - Public user-facing CLI is `pyro`. - Public Python SDK entrypoint is `from pyro_mcp import Pyro`. +- The packaged runtime images under `src/pyro_mcp/runtime_bundle/` are stored in Git LFS. - Use `make runtime-bundle` to regenerate the packaged runtime bundle from `runtime_sources/`. - Use `make runtime-materialize` to build real runtime inputs into `build/runtime_sources/`. - Use `make runtime-fetch-binaries`, `make runtime-build-kernel-real`, and `make runtime-build-rootfs-real` if you need to debug the real-source pipeline step by step. @@ -24,6 +26,8 @@ This repository ships `pyro-mcp`, an MCP-compatible package for ephemeral VM lif - Use `make doctor` to inspect bundled runtime integrity and host prerequisites. - Network-enabled flows require host privilege for TAP/NAT setup; the current implementation uses `sudo -n` for `ip`, `nft`, and `iptables` when available. - If you need full log payloads from the Ollama demo, use `make ollama-demo OLLAMA_DEMO_FLAGS=-v`. +- After heavy runtime work, reclaim local space with `rm -rf build` and `git lfs prune`. +- The pre-migration `pre-lfs-*` tag is local backup material only; do not push it or it will keep the old giant blobs reachable. ## Quality Gates diff --git a/README.md b/README.md index d81e559..4b2e81e 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,28 @@ pyro mcp serve The public user-facing interface is `pyro` and `Pyro`. `Makefile` targets are contributor conveniences for this repository and are not the primary product UX. +## Repository Storage + +This repository uses Git LFS for the packaged runtime images under +`src/pyro_mcp/runtime_bundle/`. + +Fresh contributor setup: + +```bash +git lfs install +git clone +cd pyro +git lfs pull +make setup +``` + +The large files tracked through LFS are: + +- `src/pyro_mcp/runtime_bundle/**/rootfs.ext4` +- `src/pyro_mcp/runtime_bundle/**/vmlinux` + +If you are working from an older clone created before the LFS migration, reclone or realign your branch to the rewritten history before doing more work. + ## Capabilities - Firecracker microVM execution with bundled runtime artifacts @@ -198,3 +220,12 @@ Runtime build and validation helpers remain available through `make`, including: - `make runtime-materialize` - `make runtime-boot-check` - `make runtime-network-check` + +Space cleanup after runtime work: + +```bash +rm -rf build +git lfs prune +``` + +Recreating `.venv/` is also a straightforward way to reclaim local disk if needed. diff --git a/runtime_sources/README.md b/runtime_sources/README.md index 866cfa3..372c47e 100644 --- a/runtime_sources/README.md +++ b/runtime_sources/README.md @@ -7,6 +7,7 @@ Current state: - the checked-in tracked files under `runtime_sources/linux-x86_64/` are build recipes and lock metadata, not the materialized binaries/images. - `guest/pyro_guest_agent.py` is the guest agent source artifact that is installed into each built rootfs. - real source materialization now writes into `build/runtime_sources/`, not back into the tracked placeholder files. +- the packaged runtime images under `src/pyro_mcp/runtime_bundle/` are stored via Git LFS, so contributor clones need `git lfs install` and LFS-enabled checkout. Materialization workflow: 1. `make runtime-fetch-binaries`