A lightweight, stateless Golang service exposing libvirt hypervisors over a simple REST API.
Great as a building block for custom cloud control-planes, auto-scaling clusters or edge-compute node agents.
- Stateless: no local database, all state lives in libvirt
- Full libvirt domain lifecycle: define, start, stop, reboot, undefine
- Snapshot management
- Pluggable auth (e.g. Bearer token)
- Cached image downloads
- Go 1.18+
- Libvirt (client libraries and daemon)
git clone https://github.com/UltraSive/libvirt-hypervisor-controller.git
cd libvirt-hypervisor-controller
chmod +x packages.sh
./packages.sh
make build
# Set your libvirt URI (e.g. qemu:///system)export LIBVIRT_URI=qemu:///system
# Optional: listening address (default :8080)export LISTEN_ADDR=:9090
./main| ENV Variable | Required | Default | Description |
|---|---|---|---|
| NODE_ID | false | NODE_1 | The node ID for webhook events |
| LIBVIRT_URI | false | qemu:///system | libvirt connection URI (required) |
| PORT | false | 8080 | HTTP bind address |
| DEFINITIONS_DIR | false | /data/vm | Path where libvirt domain xml stored |
| AUTH_TOKEN | false | — | Static bearer token for simple auth |
| WEBHOOK_ENDPOINT | false | — | HTTP endpoint for events |
| CACHE_DIR | false | — | Cache for VM image templates |
| CACHE_SECONDS | false | — | How long should VM images be cached |
When WEBHOOK_ENDPOINT is set, the controller will emit HTTP POST requests to the specified endpoint on major domain lifecycle changes. Each event contains the domain_id and event_type.
{
"object": "event",
"node_id": "NODE_1",
"domain_id": "vm-123",
"type": "domain.defined",
"data": {},
"timestamp": "2024-05-23T18:25:43.511Z"
}| Event Type | Description |
|---|---|
domain.defined | Domain was defined (created) |
domain.started | Domain was started |
domain.stopped | Domain was gracefully stopped |
domain.shutdown | Domain shutdown was initiated |
domain.rebooted | Domain was rebooted |
domain.undefined | Domain was deleted/undefined |
domain.snapshot_created | A snapshot was created |
domain.snapshot_deleted | A snapshot was deleted |
This project is licensed under the MIT License. See LICENSE for details.