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

Use these endpoints to start, stop, force-stop, pause, resume, or reset a VM, and to press keys in a running guest. Lifecycle commands are asynchronous: a successful response usually means the command was accepted, so use getVm to observe the resulting state. A start can also be refused in a 200 response.

Every 200 response below uses the VM detail shape.

FieldTypeRequiredDescription
namestringYesThe VM name.
vm_idstringNoThe VM identifier, represented by 16 lowercase hexadecimal digits.
statestringYesCurrent state: Creating, Stopped, Starting, Running, Paused, Stopping, Failed, or Orphaned.
reasonstringNoProse explanation of the current condition. A Failed VM without error carries only reason.
runstringNoIdentifier for the current VM run.
progressobjectNoProgress reported while the VM is being created.
progress.phasestringYesProgress phase: reserving, importing, committing, committed, or failed.
progress.bytes_doneintegerYesNumber of bytes processed.
progress.bytes_totalintegerYesTotal number of bytes to process.
progress.fell_backstringNoSet when the disk could not be cloned by reflink and was copied instead.
progress.warningsarrayNoWarnings about a create that succeeded.
progress.errorobjectNoPresent when progress.phase is failed.
progress.error.errorobjectYesNested error envelope for the failed create.
progress.error.error.codestringYesMachine-readable error code.
progress.error.error.messagestringYesHuman-readable explanation.
progress.error.error.retryablebooleanYesWhether repeating the identical request could succeed without another change.
sidecarsarrayNoHealth of the VM’s helper processes. Omitted when empty.
sidecars[].kindstringYesHelper kind: passt, virtiofsd, or swtpm.
sidecars[].statestringYesHelper state: absent, starting, ready, degraded, or stopped.
specobjectNoThe VM’s committed configuration. It can be absent while the VM is being created, when it cannot be read, or while it is changing between consecutive reads.
spec.memory_mibintegerYesGuest RAM in MiB. Mutable while stopped.
spec.vcpusintegerYesNumber of virtual CPUs. Mutable while stopped.
spec.disk_bytesintegerNoSize of the system disk in bytes. Mutable while stopped, grow only.
spec.firmwarestringYesFirmware type: uefi, uefi-secure-boot, or bios.
spec.busstringYesSystem disk controller: virtio or sata.
spec.display_adapterstringYesDisplay adapter: vga or virtio-vga.
spec.cpustringYesCPU model: qemu-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.
spec.consolebooleanYesWhether the VM has a serial console.
spec.console_inputbooleanYesWhether console input can be written to the VM.
spec.audiostringYesAudio mode: none or output.
spec.machine_typestringYesThe QEMU machine type assigned to the VM.
spec.displayintegerNoX display number. Absent for a headless VM.
spec.cdromsarrayNoAttached read-only media in boot order.
spec.autostartbooleanYesWhether the VM starts automatically when the service starts.
spec.disk_bpsintegerNoDisk throughput limit in bytes per second.
spec.disk_iopsintegerNoDisk operations per second limit.
spec.share_quota_bytesintegerNoSize limit in bytes for the VM’s share/ folder. Checked when the VM starts.
spec.portsarrayNoInbound port forwards. At most 128 rules can be configured.
spec.ports[].protostringNoTransport protocol: tcp or udp. Default: "tcp".
spec.ports[].hostintegerYesPort opened on the computer, from 1 through 65535.
spec.ports[].guestintegerYesPort the guest listens on, from 1 through 65535.
spec.stop_grace_secondsintegerNoHow long a graceful stop waits for the guest to power itself down before stopping it forcibly, in seconds. Absent when the default of 30 seconds applies. Mutable while stopped.
display_urlstringNoBrowser address of the VM’s screen. Present only in the getVm response when a display is configured.
monitor_stalledbooleanNoIndicates that the QMP monitor has stopped answering control commands. The VM can still read Running.
seqintegerNoThe VM’s event counter as of the response.
errorobjectNoNested error envelope for a failed run. The code is at error.error.code.
error.errorobjectYesError details, present when error is present.
error.error.codestringYesMachine-readable error code.
error.error.messagestringYesHuman-readable explanation.
error.error.retryablebooleanYesWhether repeating the identical request could succeed without another change.
shareobjectNoDisk usage of the VM’s share/ folder.
share.bytesintegerYesAllocated size in bytes.
share.partialbooleanYesWhether the measurement stopped early, making bytes a lower bound.
share.sampled_unixintegerYesMeasurement time in Unix seconds.
share.quota_bytesintegerNoCurrent quota in bytes. Absent when the share has no size limit.
share.over_quotabooleanYesLatched state from the last quota crossing.

HTTP error responses use this shape.

FieldTypeRequiredDescription
errorobjectYesError details.
error.codestringYesMachine-readable error code. Branch on this value rather than on error.message.
error.messagestringYesHuman-readable explanation.
error.retryablebooleanYesWhether repeating the identical request could succeed without another change.

seq is the VM’s event counter on state frames and in VM reads.

  • A per-VM resync uses data.detail.seq when the detail includes a sequence number.
  • If the detail has no seq, such as a VM being created or a resync carrying data.error, the resync repeats the stream’s last known seq. That repeated value does not prove the current counter, so re-read the VM.
  • The sequence number is 0 on the all-VMs stream’s resync, on the uncounted kinds progress, sidecar, qmp-error, snapshot, share-quota, monitor-stalled, and deleted, and on the state frame that ends a create.
  • Process every resync, regardless of its seq.

share.over_quota is the latched state left by the last quota crossing. It is not a comparison with the latest measurement.

  • It becomes true when a measurement exceeds the quota. A partial measurement counts because its size is a lower bound.
  • It becomes false only when a complete measurement is at or below the return level, quota - quota / 16, using integer division rounded down, or when the quota is removed.
  • A partial measurement never clears the state, so over_quota can remain true below the quota within the hysteresis band.
  • Changing the quota rechecks the last measurement and can change the state.
  • Each change of over_quota publishes one share-quota event.
  • over_quota is always false when there is no quota.

POST /api/v1/vm/vms/{name}/start

Starts a VM. A refused start can still return 200, so inspect error before reading state. The 400, 404, 409, and 507 statuses are the only HTTP error statuses for this operation.

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

This endpoint does not accept a request body.

Terminal window
curl --request POST \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/start'

Media type: application/json

A populated error means the start was refused, even when state still reads Starting. The refusal code is at error.error.code. If error is absent, poll getVm until state is Running or Failed.

The following codes are deferred. They arrive in the VM’s error, not as the HTTP status.

{
"name": "dev-vm",
"vm_id": "0000019a3f5c2e11",
"state": "Starting",
"seq": 41,
"error": {
"error": {
"code": "KvmUnavailable",
"message": "Hardware virtualization is unavailable on this computer.",
"retryable": false
}
}
}
Error CodeTitleDescriptionResolution
SpecInvalidInvalid start configurationA stored host port is below the computer’s current unprivileged port start value.Stop the VM, correct the stored port configuration, and start it again.
SourceBusySource is busyA resource required by the start is currently busy.Wait for the resource to become available and retry.
KvmUnavailableKVM unavailableThe computer cannot provide the required virtualization capability.Check virtualization availability on the computer and retry.
KvmCapExceededComputer KVM limit exceededThe computer’s KVM limit for VMs, vCPUs, or memory slots has been reached.Change the VM configuration or stop another VM to free capacity on the computer, then retry.
MemoryExceedsCgroupMemory limit exceededThe VM’s memory requirement exceeds the available computer limit.Reduce the requested memory or increase the computer’s limit, then retry.
QemuExecFailedQEMU execution failedThe service could not execute QEMU for the start.Correct the launch problem reported by the service and retry.
QemuExitedBeforeReadyQEMU exited before readyQEMU exited before the VM became ready.Inspect the VM run and service logs, correct the cause, and retry.
QmpHandshakeFailedQMP handshake failedQEMU started, but its control handshake did not complete.Inspect the launch failure, correct the control connection problem, and retry.
StartupIndeterminateStartup result indeterminateThe service could not determine the outcome of the launch.Re-read the VM to establish whether it is Running or Failed before retrying.
StorageFailedStorage setup failedThe VM’s storage could not be prepared for the start. This error is not retryable.Correct the storage problem reported by the service and retry.
JournalFailedState persistence failedThe service could not persist the VM’s launch state.Check service health, then retry after state persistence is available.
DisplayUnavailableDisplay unavailableThe configured display could not be provided for the VM.Correct the display availability problem and retry.
DisplayInUseDisplay already in useThe display required by the VM is already in use.Release the conflicting display assignment, then retry.
SidecarUnavailableHelper process unavailableA VM helper process, such as the network, shared-folder, or TPM helper, could not start.Inspect the helper state, correct the reported problem, and retry.
AudioBackendUnavailableAudio backend unavailableThe configured audio backend could not be started.Make an available audio backend available or use an audio configuration supported by the computer, then retry.
TpmStateMissingTPM state missingThe VM’s required TPM state is unavailable.Correct the missing TPM state reported by the service and retry.

POST /api/v1/vm/vms/{name}/stop

Stops a VM gracefully. The VM reads Stopping until its process exits, then reads Stopped. Poll getVm until the stop completes.

The body is optional. grace_seconds sets this stop’s grace period, from 5 through 900 seconds. Without it, the VM’s stop_grace_seconds applies, or 30 seconds when that is not set. The grace period is fixed when the stop is accepted: stopping a VM that is already stopping changes nothing, while a force-stop cuts a graceful stop short.

NameInTypeRequiredDescription
namepathstringYesThe VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters.
FieldTypeRequiredDescription
grace_secondsintegerNoHow long this stop waits for the guest to power itself down before stopping it forcibly, in seconds, from 5 through 900. Overrides the VM’s stop_grace_seconds for this stop only.

Omit the body, or send {}, to use the VM’s own grace period.

Terminal window
curl --request POST \
--header 'Content-Type: application/json' \
--data '{"grace_seconds": 60}' \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/stop'

Media type: application/json

The stop was accepted. Poll getVm until state is Stopped.

{
"name": "dev-vm",
"vm_id": "0000019a3f5c2e11",
"state": "Stopping",
"seq": 42
}

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

Force-stops a VM. Poll getVm until state is Stopped.

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

This endpoint does not accept a request body.

Terminal window
curl --request POST \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/force-stop'

Media type: application/json

The force-stop was accepted. Poll getVm until state is Stopped.

{
"name": "dev-vm",
"vm_id": "0000019a3f5c2e11",
"state": "Stopping",
"seq": 45
}

POST /api/v1/vm/vms/{name}/pause

Pauses a VM. Poll getVm until state is Paused.

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

This endpoint does not accept a request body.

Terminal window
curl --request POST \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/pause'

Media type: application/json

The pause was accepted. Poll getVm until state is Paused.

{
"name": "dev-vm",
"vm_id": "0000019a3f5c2e11",
"state": "Paused",
"seq": 43
}

POST /api/v1/vm/vms/{name}/resume

Resumes a paused VM. Poll getVm until state is Running.

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

This endpoint does not accept a request body.

Terminal window
curl --request POST \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/resume'

Media type: application/json

The resume was accepted. Poll getVm until state is Running.

{
"name": "dev-vm",
"vm_id": "0000019a3f5c2e11",
"state": "Running",
"seq": 44
}

POST /api/v1/vm/vms/{name}/reset

Presses the VM’s reset button. The guest restarts at once without shutting down, exactly as with a physical reset. The VM keeps its process, its run and its Running state. Only a running VM can be reset: resume a paused VM first. The call returns once QEMU has answered, at most 10 seconds, the monitor command deadline.

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

This endpoint does not accept a request body.

Terminal window
curl --request POST \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/reset'

Media type: application/json

QEMU carried out the reset and the guest is rebooting. The VM keeps its Running state, so a VM read cannot confirm that the guest booted. Check the guest on its display, console, or agent to confirm that it booted.

{
"name": "dev-vm",
"vm_id": "0000019a3f5c2e11",
"state": "Running",
"seq": 47
}

POST /api/v1/vm/vms/{name}/keys

Presses one key combination in the guest, as on its keyboard. The keys go down together in the order given and come up in reverse, so ["ctrl", "alt", "delete"] is Ctrl+Alt+Del. Send one request per combination. Only a running VM accepts keys. The call returns once QEMU has answered, at most 10 seconds, the monitor command deadline.

NameInTypeRequiredDescription
namepathstringYesThe VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters.
FieldTypeRequiredDescription
keysarrayYesThe keys to press together, in order, using QEMU’s key names. Between 1 and 8 keys, each one different.
hold_msintegerNoHow long the keys are held down, in milliseconds, from 10 through 1000. Omitted means QEMU’s default of 100 ms.

Accepted key names:

GroupNames
Lettersa through z
Digits0 through 9
Function keysf1 through f12
Modifiersshift, shift_r, ctrl, ctrl_r, alt, alt_r, meta_l, meta_r
Editing and navigationesc, tab, ret, spc, backspace, delete, insert, home, end, pgup, pgdn, up, down, left, right
Lock and system keyscaps_lock, num_lock, scroll_lock, sysrq, pause, menu
Punctuationminus, equal, bracket_left, bracket_right, semicolon, apostrophe, grave_accent, backslash, comma, dot, slash, less
Keypadkp_0 through kp_9, kp_add, kp_subtract, kp_multiply, kp_divide, kp_enter, kp_decimal

Power, sleep and wake keys are not accepted: use the lifecycle routes.

Terminal window
curl --request POST \
--header 'Content-Type: application/json' \
--data '{"keys": ["ctrl", "alt", "delete"]}' \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/keys'

Media type: application/json

QEMU pressed the keys. The VM stays in its current state.

{
"name": "dev-vm",
"vm_id": "0000019a3f5c2e11",
"state": "Running",
"seq": 46
}