Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

The Hoody VM service manages QEMU virtual machines with KVM inside a Hoody computer. Use these operations to verify host readiness before creating a VM, inspect usable templates, check service health, and collect Prometheus metrics.

Access to the service is controlled by the computer’s proxy permission rules. TypeScript SDK calls resolve to { statusCode, message, data }, so operation fields are read from data.

VMs

List, create, inspect, reconfigure and delete VMs. Open the VMs page.

Lifecycle

Start, stop, force-stop, pause and resume a VM. Open the Lifecycle page.

Events

Server-Sent Events streams for one VM or every VM. Open the Events page.

Recovery

Orphaned VMs and runs held under no VM name. Open the Recovery page.

GET /api/v1/vm/capabilities

Returns the host’s virtualization features, resource budgets, admitted memory, provisioning support and free storage.

This endpoint takes no parameters and accepts no request body.

Terminal window
curl --request GET \
--url 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/capabilities'

Media type: application/json

Returns the host capabilities.

FieldTypeRequiredDescription
kvm_presentbooleanYesWhether KVM is available. The service does not fall back to software emulation.
fuse_presentbooleanYesWhether FUSE is available on the host.
unprivileged_port_startinteger or nullYesLowest port that unprivileged processes may bind. It may be 0, and it is null when the value cannot be read.
memoryobjectYesMemory capacity and allocations admitted to VM runs.
memory.ceiling_bytesinteger or nullYesThe computer’s memory limit in bytes, or null when it has no memory limit. The key is always present.
memory.admittedarrayYesMemory currently held by identified and unidentified runs.
memory.admitted[].namestringNoName of the VM holding the memory. Present instead of unidentified_run.
memory.admitted[].unidentified_runstringNoIdentifier of a run holding memory that could not be matched to a VM. It contains exactly 16 lowercase hexadecimal digits and is never all zeros. Present instead of name.
memory.admitted[].admitted_bytesinteger or nullYesBytes of memory held by the run, or null when it holds the whole limit of a computer that has no limit. The key is always present.
memory.admitted[].estimatedbooleanNoWhether admitted_bytes is a reservation rather than a measurement.
miscobjectYesKVM resource budgets.
misc.kvm_vmobject or nullNoBudget for the kvm_vm resource. Optional, and null when the host reports no budget.
misc.kvm_vm.usedintegerYesAmount currently used. Required when misc.kvm_vm is present.
misc.kvm_vm.ceilingintegerYesMaximum permitted amount. Required when misc.kvm_vm is present.
misc.kvm_vcpuobject or nullNoBudget for the kvm_vcpu resource. Optional, and null when the host reports no budget.
misc.kvm_vcpu.usedintegerYesAmount currently used. Required when misc.kvm_vcpu is present.
misc.kvm_vcpu.ceilingintegerYesMaximum permitted amount. Required when misc.kvm_vcpu is present.
misc.kvm_memslotobject or nullNoBudget for the kvm_memslot resource. Optional, and null when the host reports no budget.
misc.kvm_memslot.usedintegerYesAmount currently used. Required when misc.kvm_memslot is present.
misc.kvm_memslot.ceilingintegerYesMaximum permitted amount. Required when misc.kvm_memslot is present.
provisioningobjectYesFeatures available when creating VMs.
provisioning.uefibooleanYesWhether UEFI VMs can be created. UEFI is the default firmware, so when this is false, create VMs with "firmware": "bios" or the create fails.
provisioning.virtio_win_isobooleanYesWhether a virtio-win driver ISO is attached automatically as a second CD-ROM beside an installer ISO.
provisioning.templatesbooleanYesWhether the host has a template catalog for template disk sources.
provisioning.machine_typestringYesMachine type, such as pc-q35-<version>, assigned to newly created VMs. Existing VMs retain their original machine type.
provisioning.tpmbooleanYesWhether TPM 2.0 can be enabled. Windows 11 requires a TPM.
provisioning.secure_bootbooleanYesWhether Secure Boot can be enabled and enforced with Microsoft keys. Windows 11 requires Secure Boot and a TPM.
provisioning.audiobooleanYesWhether VMs can have a sound device. A start can still fail with AudioBackendUnavailable if the desktop audio socket has no listener.
provisioning.file_sharingbooleanYesWhether the host can serve a shared folder into guests using virtiofsd.
storageobjectYesStorage information for VM data.
storage.free_bytesintegerYesFree storage bytes at the time of the request. This value is informational and does not reserve space.
{
"kvm_present": true,
"fuse_present": true,
"unprivileged_port_start": 1024,
"memory": {
"ceiling_bytes": 17179869184,
"admitted": [
{
"name": "debian-test",
"admitted_bytes": 2147483648,
"estimated": false
},
{
"unidentified_run": "4f1c9a2e7b3d5a60",
"admitted_bytes": 1073741824,
"estimated": true
}
]
},
"misc": {
"kvm_vm": {
"used": 3,
"ceiling": 64
},
"kvm_vcpu": {
"used": 4,
"ceiling": 128
},
"kvm_memslot": {
"used": 4,
"ceiling": 32
}
},
"provisioning": {
"uefi": true,
"virtio_win_iso": true,
"templates": true,
"machine_type": "pc-q35-8.1",
"tpm": true,
"secure_boot": true,
"audio": false,
"file_sharing": true
},
"storage": {
"free_bytes": 53687091200
}
}

GET /api/v1/vm/health

Returns the service status and runtime information. The response has exactly nine top-level fields: status, service, built, started, memory, fds, pid, ip and userAgent.

This endpoint takes no parameters and accepts no request body.

Terminal window
curl --request GET \
--url 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/health'

Media type: application/json

The service is running.

FieldTypeRequiredDescription
statusstringYesService status.
servicestringYesService name.
builtstring or nullYesService build time.
startedstringYesService start time.
memoryobject or nullYesService memory use.
memory.rssintegerYesResident set size in bytes. Required when memory is present.
memory.heapinteger or nullYesHeap usage in bytes. It is currently always null. Required when memory is present.
fdsinteger or nullYesNumber of open file descriptors.
pidintegerYesService process identifier.
ipstringYesCaller’s address.
userAgentstring or nullYesCaller’s user agent.
{
"status": "ok",
"service": "hoody-vm",
"built": "2026-02-18T12:00:00Z",
"started": "2026-02-18T12:05:00Z",
"memory": {
"rss": 73400320,
"heap": null
},
"fds": 38,
"pid": 2417,
"ip": "192.0.2.42",
"userAgent": "curl/8.7.1"
}

GET /api/v1/vm/metrics

Returns VM metrics in the Prometheus text exposition format. The service also serves the metrics at /metrics without the API prefix for scrapers that expect a fixed path.

This endpoint takes no parameters and accepts no request body.

The endpoint declares these 26 metric families:

Metric family
process_uptime_seconds
process_resident_memory_bytes
hoody_vm_vms_by_state
hoody_vm_starts_total
hoody_vm_stops_total
hoody_vm_failures_total
hoody_vm_qmp_errors_total
hoody_vm_monitor_stalls_total
hoody_vm_autostart_failures_total
hoody_vm_share_sample_failures_total
hoody_vm_share_quota_refusals_total
hoody_vm_sidecar_restarts_total
hoody_vm_adoptions_total
hoody_vm_permits_held
hoody_vm_permits_orphaned
hoody_vm_permits_leaked
hoody_vm_unidentified_runs
hoody_vm_unidentified_run_bytes
hoody_vm_admitted_guest_ram_bytes
hoody_vm_admitted_permit_bytes
hoody_vm_reflink_fallbacks_total
hoody_vm_share_bytes
hoody_vm_share_sample_partial
hoody_vm_share_quota_bytes
hoody_vm_share_over_quota
http_requests_total
  • hoody_vm_vms_by_state{state} always carries a series for each of the eight VM states.
  • hoody_vm_sidecar_restarts_total{kind,degraded} always carries a series for each of the three helper processes, even when the value is zero.
  • The four shared-folder measurement families, hoody_vm_share_bytes, hoody_vm_share_sample_partial, hoody_vm_share_quota_bytes and hoody_vm_share_over_quota, are always declared. A VM appears in them only after its shared folder has been measured, so a missing series means not yet measured, not zero.
  • hoody_vm_share_quota_bytes and hoody_vm_share_over_quota include only VMs that have a shared-folder quota.
Terminal window
curl --request GET \
--url 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/metrics'

Media type: text/plain; version=0.0.4; charset=utf-8

The response body is a string in the Prometheus exposition format.

Representative body:

process_uptime_seconds 3600
process_resident_memory_bytes 73400320
hoody_vm_starts_total 12
hoody_vm_stops_total 8
hoody_vm_failures_total 1
http_requests_total{method="GET",path="/api/v1/vm/health",status="200"} 245

GET /api/v1/vm/templates

Lists the templates available on the host. Every returned id can be used as a template disk source, for example {"source":{"type":"template","id":"debian-12"}}.

This endpoint takes no parameters and accepts no request body.

Terminal window
curl --request GET \
--url 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/templates'

Media type: application/json

Returns the templates sorted by id. The list is empty when the host has no template catalog. In that case, provisioning.templates from the capabilities operation is false.

FieldTypeRequiredDescription
[].idstringYesTemplate identifier. It must match ^[a-z0-9][a-z0-9-]{0,62}$.
[].disk_bytesintegerYesSize of the template disk in bytes. This is also the smallest disk that a VM created from the template can have.
[
{
"id": "debian-12",
"disk_bytes": 3221225472
},
{
"id": "ubuntu-2404",
"disk_bytes": 4294967296
}
]