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.
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 demo to validate deterministic VM lifecycle execution.
Use make ollama-demo to validate model-triggered lifecycle tool usage.
Use make doctor to inspect bundled runtime integrity and host prerequisites.
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 factory: pyro_mcp.create_server()
Runtime diagnostics CLI: pyro-mcp-doctor
Runtime bundle build CLI: pyro-mcp-runtime-build
Current bundled runtime is shim-based unless replaced with a real guest-capable bundle; check make doctor for runtime capabilities.
Lifecycle tools:
- vm_list_profiles
- vm_create
- vm_start
- vm_exec
- vm_stop
- vm_delete
- vm_status
- vm_network_info
- vm_reap_expired