64 lines
3.5 KiB
Markdown
64 lines
3.5 KiB
Markdown
# 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.
|
|
- Use `make pypi-publish` for manual PyPI uploads after setting `TWINE_PASSWORD`.
|
|
- 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`.
|
|
- `pyro run` now defaults to `1 vCPU / 1024 MiB`, human-readable output, and fail-closed guest execution unless `--allow-host-compat` is passed.
|
|
- 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 Docker Hub publication is performed locally with `make runtime-publish-official-environments-oci`.
|
|
|
|
## 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`
|