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 VM recovery endpoints of a computer’s VM service handle two failure shapes: a run that lost its VM name, and a VM left Orphaned. Use them to list the runs that hold memory under no VM name, to take over an orphaned VM’s run, to record an orphaned VM’s run as dead, and to release an unidentified run.

Who may call these routes is set by the computer’s proxy permission rules.

GET /api/v1/vm/unidentified-runs

Lists the runs that hold memory against this computer under no VM name. The list is normally empty. Each entry holds memory against this computer, so a non-empty list can explain why VM starts are refused for lack of memory.

This endpoint takes no parameters.

The unidentified runs, in no particular order. Normally empty.

Media type: application/json

[
{
"run": "4f1c9a2e7b3d5a60",
"reason": "unreadable-journal",
"liveness": "unknown",
"admitted_bytes": 536870912,
"estimated": true,
"clear_route": "/api/v1/vm/unidentified-runs/4f1c9a2e7b3d5a60/force-mark-dead"
}
]

Each entry describes one unidentified run.

FieldTypeRequiredDescription
runstringYesThe run ID: 16 lowercase hexadecimal digits, never all zeros. Pass it when marking this run as dead, which releases the memory it holds.
reasonstringYesWhy this run has no VM name. Always unreadable-journal.
livenessstringYesAlways unknown: no process is recorded for the run, so the service cannot tell whether it is alive. Clearing it therefore needs a human’s confirmation.
admitted_bytesinteger or nullYesBytes of memory held against this run. This is the whole memory ceiling, because the run’s real size is unknown. null when the computer has no memory limit. The key is always present.
estimatedbooleanYesAlways true: admitted_bytes is an estimate, not a measurement.
clear_routestringYesThe route that releases this run’s memory. It names the same run ID as run.
Terminal window
curl -X GET "https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/unidentified-runs"

POST /api/v1/vm/unidentified-runs/{run}/force-mark-dead

Records an unidentified run as dead, releases the memory it holds and moves the run’s files aside instead of deleting them. The run ID is named twice, in the path and as confirm_run in the request body, so a body that names a different run is refused.

NameInTypeRequiredDescription
runpathstringYesThe run ID from GET /unidentified-runs: 16 lowercase hexadecimal digits, never all zeros.
FieldTypeRequiredDescription
confirm_runstringYesMust equal {run} in the path. Naming the run twice guards against clearing the wrong one.
{
"confirm_run": "4f1c9a2e7b3d5a60"
}

The memory was released and the run’s files were moved aside, not deleted.

Media type: none. The response has no body.

Terminal window
curl -X POST "https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/unidentified-runs/4f1c9a2e7b3d5a60/force-mark-dead" \
-H "Content-Type: application/json" \
-d '{"confirm_run": "4f1c9a2e7b3d5a60"}'

POST /api/v1/vm/vms/{name}/force-adopt

Resumes managing an orphaned VM’s run. The service takes the run back under management and the VM becomes managed again.

NameInTypeRequiredDescription
namepathstringYesThe VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters.

This endpoint takes no request body.

The run was adopted and the VM is managed again. The body is a VM detail object, whose fields are listed under VM detail fields.

Media type: application/json

{
"name": "dev-vm",
"vm_id": "0000019a3f5c2e11",
"state": "Running",
"run": "4f1c9a2e7b3d5a60",
"progress": {
"phase": "committed",
"bytes_done": 10737418240,
"bytes_total": 10737418240
},
"sidecars": [
{ "kind": "passt", "state": "ready" },
{ "kind": "virtiofsd", "state": "ready" },
{ "kind": "swtpm", "state": "ready" }
],
"spec": {
"memory_mib": 2048,
"vcpus": 2,
"disk_bytes": 10737418240,
"firmware": "uefi",
"bus": "virtio",
"display_adapter": "virtio-vga",
"cpu": "qemu-default",
"tpm": true,
"file_sharing": true,
"agent": true,
"console": true,
"console_input": true,
"audio": "none",
"machine_type": "q35",
"display": 1,
"autostart": false,
"share_quota_bytes": 1073741824,
"ports": [
{ "proto": "tcp", "host": 2222, "guest": 22 }
]
},
"share": {
"bytes": 1048576,
"partial": false,
"sampled_unix": 1760000000,
"quota_bytes": 1073741824,
"over_quota": false
},
"seq": 42
}
Terminal window
curl -X POST "https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/force-adopt"

POST /api/v1/vm/vms/{name}/force-mark-dead

Records an orphaned VM’s run as dead. The VM is no longer Orphaned and can be started or deleted. The operation is accepted only when the VM’s disk is not locked.

NameInTypeRequiredDescription
namepathstringYesThe VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters.

This endpoint takes no request body.

The run was marked dead. The VM is no longer Orphaned and can be started or deleted. The body is a VM detail object, whose fields are listed under VM detail fields.

Media type: application/json

{
"name": "dev-vm",
"vm_id": "0000019a3f5c2e11",
"state": "Stopped",
"run": "4f1c9a2e7b3d5a60",
"progress": {
"phase": "committed",
"bytes_done": 10737418240,
"bytes_total": 10737418240
},
"sidecars": [
{ "kind": "passt", "state": "ready" },
{ "kind": "virtiofsd", "state": "ready" },
{ "kind": "swtpm", "state": "ready" }
],
"spec": {
"memory_mib": 2048,
"vcpus": 2,
"disk_bytes": 10737418240,
"firmware": "uefi",
"bus": "virtio",
"display_adapter": "virtio-vga",
"cpu": "qemu-default",
"tpm": true,
"file_sharing": true,
"agent": true,
"console": true,
"console_input": true,
"audio": "none",
"machine_type": "q35",
"display": 1,
"autostart": false,
"share_quota_bytes": 1073741824,
"ports": [
{ "proto": "tcp", "host": 2222, "guest": 22 }
]
},
"share": {
"bytes": 1048576,
"partial": false,
"sampled_unix": 1760000000,
"quota_bytes": 1073741824,
"over_quota": false
},
"seq": 43
}
Terminal window
curl -X POST "https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/force-mark-dead"

The 200 responses of force-adopt and force-mark-dead return the same VM detail object.

FieldTypeRequiredDescription
namestringYesThe VM name.
vm_idstringNoThe VM’s identifier: 16 lowercase hexadecimal digits.
statestringYesOne of Creating, Stopped, Starting, Running, Paused, Stopping, Failed, Orphaned.
reasonstringNoHuman-readable reason for the current state. Present on Failed and Orphaned, absent otherwise.
runstringNoThe run ID: 16 lowercase hexadecimal digits, never all zeros.
progress.phasestringYesOne of reserving, importing, committing, committed, failed.
progress.bytes_doneintegerYesBytes written so far.
progress.bytes_totalintegerYesBytes expected in total.
progress.fell_backstringNoSet when the disk could not be cloned by reflink and was fully copied instead, which takes longer and uses more space.
progress.warningsarray of stringNoThings you should know about a create that succeeded. Omitted when there are no warnings.
progress.error.error.codestringYesThe error code for a failed create.
progress.error.error.messagestringYesHuman-readable message for the failed create.
progress.error.error.retryablebooleanYesWhether repeating the identical request could succeed without anything else changing.
sidecars[].kindstringYesWhich helper: passt for the guest’s network, virtiofsd for its shared folder, swtpm for its TPM.
sidecars[].statestringYesOne of absent, starting, ready, degraded, stopped.
spec.memory_mibintegerYesGuest RAM in MiB.
spec.vcpusintegerYesNumber of virtual CPUs.
spec.disk_bytesintegerNoSize of the system disk in bytes. Absent when the size could not be read, which does not mean zero.
spec.firmwarestringYesuefi, uefi-secure-boot or bios.
spec.busstringYesvirtio or sata.
spec.display_adapterstringYesvga or virtio-vga.
spec.cpustringYesqemu-default, westmere or host.
spec.tpmbooleanYesWhether the VM has a TPM 2.0.
spec.file_sharingbooleanYesWhether the VM’s share/ folder is shared into the guest.
spec.agentbooleanYesWhether the VM has the guest-agent channel, the device rather than whether an agent runs in the guest.
spec.consolebooleanYesWhether the VM has a serial console.
spec.console_inputbooleanYesWhether the console may be written to. Always false when spec.console is false.
spec.audiostringYesnone or output.
spec.machine_typestringYesThe QEMU machine type the VM is pinned to.
spec.displayintegerNoX display number. Absent when the VM is headless.
spec.cdromsarray of string or nullNoAttached read-only media by slot, in boot order. null is an empty slot that keeps its position. Omitted when the VM has no CD-ROM slots.
spec.autostartbooleanYesWhether the VM starts automatically when the service starts.
spec.disk_bpsintegerNoDisk throughput limit in bytes per second. Absent when unlimited.
spec.disk_iopsintegerNoDisk operations per second limit. Absent when unlimited.
spec.share_quota_bytesintegerNoSize limit in bytes for the VM’s share/ folder. Absent when unlimited.
spec.ports[].protostringNotcp or udp. Default: tcp.
spec.ports[].hostintegerYesPort opened on every address of the computer, from 1 to 65535.
spec.ports[].guestintegerYesPort the guest listens on, from 1 to 65535.
spec.stop_grace_secondsintegerNoHow long a graceful stop waits for the guest to power itself down, in seconds. Absent when the default of 30 applies.
display_urlstringNoThe address of the VM’s screen in the browser. Present only in the answer to GET /vms/{name}, and only when the VM has a display numbered above 0.
monitor_stalledbooleanNoThe QMP monitor is connected and has stopped answering. Omitted when false, so absence means healthy.
seqintegerNoThe VM’s event counter as of this response. See the note below.
error.error.codestringYesThe error code for the current run’s start failure.
error.error.messagestringYesHuman-readable message for the start failure.
error.error.retryablebooleanYesWhether repeating the identical request could succeed without anything else changing.
share.bytesintegerYesAllocated size in bytes of the VM’s share/ folder.
share.partialbooleanYestrue when the measurement stopped early, so bytes is a lower bound rather than a total.
share.sampled_unixintegerYesWhen the measurement was taken, in Unix seconds.
share.quota_bytesintegerNoThe VM’s share_quota_bytes. Absent when the share has no size limit.
share.over_quotabooleanYesThe latched over-quota state of the share. See the note below.

Every error response carries the same envelope.

FieldTypeRequiredDescription
errorobjectYesThe error object.
error.codestringYesThe error code, from a fixed set. Branch on this, not on message: the message is human-readable text and may change.
error.messagestringYesHuman-readable description of the failure.
error.retryablebooleanYesWhether repeating the identical request could succeed without anything else changing.