thaloco/pyro-mcp
1
Fork 0
Code Pull requests Releases Packages Activity Actions
pyro-mcp/AGENTS.md

3.2 KiB
Raw Blame History

AGENTS.md

Repository guidance for contributors and coding agents.

Purpose

This repository ships pyro-mcp, an MCP-compatible package for ephemeral VM lifecycle tools used by coding agents.

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.
  • Run make dist-check when you change packaging, entrypoints, or install docs.
  • 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-publish-official-environments-oci after materialization to push the official OCI environments to their configured registry targets.
  • 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.
  • If kernel materialization hits compiler crashes on a smaller host, retry with PYRO_KERNEL_BUILD_JOBS=1 make runtime-build-kernel-real or PYRO_KERNEL_BUILD_JOBS=1 make runtime-materialize.
  • Use make runtime-boot-check to run a direct Firecracker boot validation against the bundled runtime artifacts.
  • Use make runtime-network-check to validate outbound internet access from inside the guest.
  • Use make demo to validate deterministic VM lifecycle execution.
  • Use make network-demo to validate deterministic VM lifecycle execution with guest networking enabled.
  • Use make ollama-demo to validate model-triggered lifecycle tool usage with guest networking enabled.
  • 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.
  • Public contract documentation lives in docs/public-contract.md.
  • Official GHCR publication workflow lives in .github/workflows/publish-environments.yml.

Quality Gates

  • Linting: ruff
  • Type checking: mypy (strict mode)
  • Tests: pytest with coverage threshold

These checks run in pre-commit hooks and should all pass locally.

Key API Contract

  • Public SDK facade: pyro_mcp.Pyro
  • Public MCP factory: pyro_mcp.create_server()
  • Public CLI: pyro
  • Current bundled runtime is guest-capable for VM boot, guest exec, and guest networking; check make doctor for runtime capabilities.
  • Primary tool:
    • vm_run
  • Advanced lifecycle tools:
    • vm_list_environments
    • vm_create
    • vm_start
    • vm_exec
    • vm_stop
    • vm_delete
    • vm_status
    • vm_network_info
    • vm_reap_expired