README
¶
vm-manager
Prototype. An MCP + REST server that provisions cloud-provider-like VMs (IMDS, vTPM with measured boot, immutable mkosi-built OS, Kubernetes as a sysext layer) on a KVM host, so agents on the Giant Swarm agent platform can hand them to the CAPI based cluster-manager.
Sibling of agent-manager and model-manager.
API at a glance
The same operations are exposed twice from one process: REST/JSON under /api/v1
(contract: api/openapi.yaml, served at /api/v1/openapi.yaml) and
MCP tools over streamable HTTP at /mcp (through muster: x_vm-manager_<tool>). Both call
the same service and return the same JSON. Errors are {"error":{"code","message"}} with a
stable code; MCP tool errors carry the same code.
| Operation | REST | MCP tool | Writes |
|---|---|---|---|
Host capabilities: kernel, CPUs, memory, /dev/kvm, /dev/vhost-vsock, qemu / swtpm / systemd versions, OVMF image, storage providers, ready + missing |
GET /api/v1/host |
get_host |
no |
The remaining tools from the design (images, networks, VMs) land with their domain packages.
Running
make build
./vm-manager serve # 127.0.0.1:8080, anonymous
./vm-manager serve --listen 0.0.0.0:8080 --enable-oauth --oauth-base-url https://vmm.example \
--dex-issuer-url https://dex.example/dex --dex-client-id ... --dex-client-secret ... \
--oauth-trusted-audiences agent-platform
Every flag has an environment fallback named in vm-manager serve --help
(VM_MANAGER_LISTEN, VM_MANAGER_STATE_DIR, VM_MANAGER_IMAGE_DIR,
VM_MANAGER_NETWORK_SUBNET, ...). State lives under --state-dir
($XDG_STATE_HOME/vm-manager, else ~/.local/state/vm-manager), images under
--image-dir (default <state-dir>/images); /healthz and /readyz are always open.
vm-manager runs on the KVM host itself (a laptop, a GitHub Actions runner, a bare-metal
node), not in a pod: GET /api/v1/host tells you whether the host is ready and what is
missing (/dev/kvm, swtpm, the systemd storage provider, ...).
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package api publishes the vm-manager API contract.
|
Package api publishes the vm-manager API contract. |
|
Package cmd holds the vm-manager CLI.
|
Package cmd holds the vm-manager CLI. |
|
internal
|
|
|
api
Package api exposes the domain services twice from one process: REST/JSON under /api/v1 for the portal and cluster-manager, and MCP tools for muster.
|
Package api exposes the domain services twice from one process: REST/JSON under /api/v1 for the portal and cluster-manager, and MCP tools for muster. |
|
apierr
Package apierr holds the sentinel errors every domain package wraps so the API layer can map them to one HTTP status and one stable error code for REST and MCP alike (internal/api statusFor).
|
Package apierr holds the sentinel errors every domain package wraps so the API layer can map them to one HTTP status and one stable error code for REST and MCP alike (internal/api statusFor). |
|
host
Package host reports what the KVM host offers vm-manager: kernel and hardware, the devices and tools the QEMU runtime needs, the firmware the images boot with, and the systemd services the provisioner talks to.
|
Package host reports what the KVM host offers vm-manager: kernel and hardware, the devices and tools the QEMU runtime needs, the firmware the images boot with, and the systemd services the provisioner talks to. |
|
identity
Package identity carries the authenticated caller through a request: who the OAuth layer validated (subject, email, groups).
|
Package identity carries the authenticated caller through a request: who the OAuth layer validated (subject, email, groups). |
|
imds
Package imds implements the Giant Swarm instance metadata service: the HTTP side of the contract systemd-imdsd in the guest is configured for by the hwdb record the image ships (HwdbFile, generated from Keys by HwdbRecord).
|
Package imds implements the Giant Swarm instance metadata service: the HTTP side of the contract systemd-imdsd in the guest is configured for by the hwdb record the image ships (HwdbFile, generated from Keys by HwdbRecord). |
|
runtime/proc
Package proc starts and supervises the long-running host processes the VM runtime is made of: QEMU (internal/runtime/qemu) and swtpm (internal/tpm).
|
Package proc starts and supervises the long-running host processes the VM runtime is made of: QEMU (internal/runtime/qemu) and swtpm (internal/tpm). |
|
runtime/qemu
Package qemu is the process-level VM runtime: it turns a Spec into the qemu-system-x86_64 argument list, starts and supervises the process, and gives the caller the three channels back into a running VM: QMP, the serial console log and the AF_VSOCK READY notification.
|
Package qemu is the process-level VM runtime: it turns a Spec into the qemu-system-x86_64 argument list, starts and supervises the process, and gives the caller the three channels back into a running VM: QMP, the serial console log and the AF_VSOCK READY notification. |
|
server
Package server assembles the single HTTP listener: health endpoints, the REST API, and the MCP streamable-HTTP endpoint (optionally behind OAuth).
|
Package server assembles the single HTTP listener: health endpoints, the REST API, and the MCP streamable-HTTP endpoint (optionally behind OAuth). |
|
tpm
Package tpm runs the software TPM behind each VM.
|
Package tpm runs the software TPM behind each VM. |