VMs
List, create, inspect, reconfigure and delete VMs. Open the VMs page.
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.
Snapshots and export
Restore points, and exporting a snapshot in parts. Open the Snapshots and export page.
Installer images
The ISO store, URL downloads and the OS catalogue. Open the Installer images page.
Snapshot imports
Upload an exported snapshot to create a VM from it. Open the Snapshot imports page.
Console, logs and guest agent
Serial console, run logs and guest-agent reports. Open the Console, logs and guest agent 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.
curl --request GET \ --url 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/capabilities'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const capabilities = await client.vm.kit.getCapabilities();console.log(capabilities.data.kvm_present);Media type: application/json
Returns the host capabilities.
| Field | Type | Required | Description |
|---|---|---|---|
kvm_present | boolean | Yes | Whether KVM is available. The service does not fall back to software emulation. |
fuse_present | boolean | Yes | Whether FUSE is available on the host. |
unprivileged_port_start | integer or null | Yes | Lowest port that unprivileged processes may bind. It may be 0, and it is null when the value cannot be read. |
memory | object | Yes | Memory capacity and allocations admitted to VM runs. |
memory.ceiling_bytes | integer or null | Yes | The computer’s memory limit in bytes, or null when it has no memory limit. The key is always present. |
memory.admitted | array | Yes | Memory currently held by identified and unidentified runs. |
memory.admitted[].name | string | No | Name of the VM holding the memory. Present instead of unidentified_run. |
memory.admitted[].unidentified_run | string | No | Identifier 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_bytes | integer or null | Yes | Bytes 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[].estimated | boolean | No | Whether admitted_bytes is a reservation rather than a measurement. |
misc | object | Yes | KVM resource budgets. |
misc.kvm_vm | object or null | No | Budget for the kvm_vm resource. Optional, and null when the host reports no budget. |
misc.kvm_vm.used | integer | Yes | Amount currently used. Required when misc.kvm_vm is present. |
misc.kvm_vm.ceiling | integer | Yes | Maximum permitted amount. Required when misc.kvm_vm is present. |
misc.kvm_vcpu | object or null | No | Budget for the kvm_vcpu resource. Optional, and null when the host reports no budget. |
misc.kvm_vcpu.used | integer | Yes | Amount currently used. Required when misc.kvm_vcpu is present. |
misc.kvm_vcpu.ceiling | integer | Yes | Maximum permitted amount. Required when misc.kvm_vcpu is present. |
misc.kvm_memslot | object or null | No | Budget for the kvm_memslot resource. Optional, and null when the host reports no budget. |
misc.kvm_memslot.used | integer | Yes | Amount currently used. Required when misc.kvm_memslot is present. |
misc.kvm_memslot.ceiling | integer | Yes | Maximum permitted amount. Required when misc.kvm_memslot is present. |
provisioning | object | Yes | Features available when creating VMs. |
provisioning.uefi | boolean | Yes | Whether 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_iso | boolean | Yes | Whether a virtio-win driver ISO is attached automatically as a second CD-ROM beside an installer ISO. |
provisioning.templates | boolean | Yes | Whether the host has a template catalog for template disk sources. |
provisioning.machine_type | string | Yes | Machine type, such as pc-q35-<version>, assigned to newly created VMs. Existing VMs retain their original machine type. |
provisioning.tpm | boolean | Yes | Whether TPM 2.0 can be enabled. Windows 11 requires a TPM. |
provisioning.secure_boot | boolean | Yes | Whether Secure Boot can be enabled and enforced with Microsoft keys. Windows 11 requires Secure Boot and a TPM. |
provisioning.audio | boolean | Yes | Whether VMs can have a sound device. A start can still fail with AudioBackendUnavailable if the desktop audio socket has no listener. |
provisioning.file_sharing | boolean | Yes | Whether the host can serve a shared folder into guests using virtiofsd. |
storage | object | Yes | Storage information for VM data. |
storage.free_bytes | integer | Yes | Free 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 }}Media type: application/json
The request is refused if it includes any query parameter. The error code is SpecInvalid.
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | Error details. |
error.code | string | Yes | Fixed error code. Branch on this value rather than error.message. |
error.message | string | Yes | Human-readable description of the failure. |
error.retryable | boolean | Yes | Whether repeating the identical request could succeed without other changes. |
{ "error": { "code": "SpecInvalid", "message": "Unknown query parameter 'foo': this operation takes no query parameters", "retryable": false }}Media type: application/json
The host capabilities or free storage information could not be read. The error code is StorageFailed.
{ "error": { "code": "StorageFailed", "message": "Unable to read storage metadata.", "retryable": false }}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.
curl --request GET \ --url 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/health'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const health = await client.vm.kit.getHealth();console.log(health.data.status);Media type: application/json
The service is running.
| Field | Type | Required | Description |
|---|---|---|---|
status | string | Yes | Service status. |
service | string | Yes | Service name. |
built | string or null | Yes | Service build time. |
started | string | Yes | Service start time. |
memory | object or null | Yes | Service memory use. |
memory.rss | integer | Yes | Resident set size in bytes. Required when memory is present. |
memory.heap | integer or null | Yes | Heap usage in bytes. It is currently always null. Required when memory is present. |
fds | integer or null | Yes | Number of open file descriptors. |
pid | integer | Yes | Service process identifier. |
ip | string | Yes | Caller’s address. |
userAgent | string or null | Yes | Caller’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"}Media type: application/json
The request is refused if it includes any query parameter. The error code is SpecInvalid.
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | Error details. |
error.code | string | Yes | Fixed error code. Branch on this value rather than error.message. |
error.message | string | Yes | Human-readable description of the failure. |
error.retryable | boolean | Yes | Whether repeating the identical request could succeed without other changes. |
{ "error": { "code": "SpecInvalid", "message": "Unknown query parameter 'foo': this operation takes no query parameters", "retryable": false }}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.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.curl --request GET \ --url 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/metrics'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const metrics = await client.vm.kit.getMetrics();console.log(metrics.data);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 3600process_resident_memory_bytes 73400320hoody_vm_starts_total 12hoody_vm_stops_total 8hoody_vm_failures_total 1http_requests_total{method="GET",path="/api/v1/vm/health",status="200"} 245Media type: application/json
The request is refused if it includes any query parameter. The error code is SpecInvalid.
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | Error details. |
error.code | string | Yes | Fixed error code. Branch on this value rather than error.message. |
error.message | string | Yes | Human-readable description of the failure. |
error.retryable | boolean | Yes | Whether repeating the identical request could succeed without other changes. |
{ "error": { "code": "SpecInvalid", "message": "Unknown query parameter 'foo': this operation takes no query parameters", "retryable": false }}Media type: application/json
The VM list could not be read. The entire scrape fails instead of returning partial metrics, so Prometheus records up as 0. The error code is StorageFailed.
{ "error": { "code": "StorageFailed", "message": "Unable to read VM storage metadata.", "retryable": false }}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.
curl --request GET \ --url 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/templates'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const templates = await client.vm.templates.list();console.log(templates.data);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.
| Field | Type | Required | Description |
|---|---|---|---|
[].id | string | Yes | Template identifier. It must match ^[a-z0-9][a-z0-9-]{0,62}$. |
[].disk_bytes | integer | Yes | Size 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 }]Media type: application/json
The request is refused if it includes any query parameter. The error code is SpecInvalid.
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | Error details. |
error.code | string | Yes | Fixed error code. Branch on this value rather than error.message. |
error.message | string | Yes | Human-readable description of the failure. |
error.retryable | boolean | Yes | Whether repeating the identical request could succeed without other changes. |
{ "error": { "code": "SpecInvalid", "message": "Unknown query parameter 'foo': this operation takes no query parameters", "retryable": false }}Media type: application/json
The template storage operation failed. The error code is StorageFailed.
{ "error": { "code": "StorageFailed", "message": "Unable to read template storage metadata.", "retryable": false }}