vm-forgeyard

vm-forgeyard is a host-local KVM control plane for test and development virtual machines.

It provides:

• control-api: VM lifecycle, capacity, operation, IP reservation, image, run, and namespace disk endpoints

• lock-api: FIFO lock queue by namespace/resource

• mcp-api: HTTP MCP adapter for agents that need to request VMs and inspect state

• root-vm-exec: a narrow request-file executor for qcow2, libvirt lifecycle, guest bootstrap, runtime inspection, and cleanup actions

• SQLite-backed control-plane state

• repository-scoped bearer tokens with optional self-registration

• machine-readable MCP workflow contracts for bug/feature-report drafting

• dry-run modes for API and executor workflow verification

Status

This repository is the public code mirror. Private deployment inventory, local hostnames, credentials, and site-specific automation are intentionally excluded.

Related MCP server: amp-mcp-server

Install

python -m pip install -e .

Start the APIs with a host-specific config:

python -m kvm_control --config ./config.example.yaml control-api
python -m kvm_control --config ./config.example.yaml lock-api
python -m kvm_control --config ./config.example.yaml mcp-api

Use config.example.yaml as a starting point. For real VM lifecycle operations, point the storage paths at durable host storage, set auth credentials, and run the executor through an appropriately constrained privilege boundary.

Auth

If auth.admin_token or auth.admin_token_hash is set, the control and lock APIs require bearer-token authentication by default. The admin token can create persistent dev or repository tokens through:

POST /v1/admin/auth/tokens

Repository tokens use git.<repo> usernames and inherit that effective namespace. The reserved dev token accepts caller-provided namespaces and normalizes unprefixed names to dev.<name>.

Agents should look for repository-scoped tokens at ./repo.auth.token; that file is intentionally gitignored. An admin may also create a repository self-registration key with:

POST /v1/admin/auth/repository-self-registration-keys

An agent holding that self-registration key can then call:

POST /v1/auth/repository-self-registration

The response contains a repository token to write to ./repo.auth.token. Existing active repository registrations cannot be overwritten by self-registration.

auth.mode: open exists only as a rollout bridge. Requests without credentials run as anonymous admin, while provided credentials are still validated.

Agent Workflows

The MCP server exposes concept resources and workflow contracts. Agents should read kvm-control://auth/onboarding and kvm-control://concepts/agent-workflow before ordering VMs. The wait_for_vm_ready tool reports ready only after a non-interactive root SSH command succeeds against the VM's reserved IP. It does not separately verify SCP or SFTP availability.

The draft_contract_report MCP tool and scripts/draft_contract_report.py can classify observations against the workflow contracts as likely bugs, feature requests, or documentation gaps.

Development Checks

Run the unit test suite:

PYTHONPATH=src python -m unittest discover -s tests -v

Run dry-run smoke checks:

PYTHONPATH=src python scripts/sandbox_api_smoke.py
PYTHONPATH=src python scripts/check_api_dry_run.py
PYTHONPATH=src python scripts/check_browser_mobile_layer2_dry_run.py
PYTHONPATH=src python scripts/check_contracts.py
PYTHONPATH=src python scripts/check_public_hygiene.py

Check an MCP endpoint:

PYTHONPATH=src python scripts/check_mcp_agent_workflow.py --url http://127.0.0.1:8002/mcp

Public Scope

The initial public repository contains the application code, unit tests, dry-run checks, static status UI assets, and an example configuration.

Deployment automation is intentionally not included yet. Ansible roles should be published only after their defaults and examples are generalized enough to be useful outside one infrastructure environment.

Project Metadata

• Contributing

• Security policy

• Release checklist

• License

License

vm-forgeyard is licensed under the GNU General Public License version 2.0. See LICENSE.