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.

Use uv for all Python environment and command execution.
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.
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.
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.

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

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_profiles
- vm_create
- vm_start
- vm_exec
- vm_stop
- vm_delete
- vm_status
- vm_network_info
- vm_reap_expired