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

These endpoints manage virtual machines hosted by a Hoody computer. Use them to list VMs, inspect state and creation progress, create a VM, reconfigure a stopped VM, open a VM’s screen, or permanently delete a VM.

The service hostname identifies the target computer.

GET /api/v1/vm/vms

Returns every known VM, including VMs whose creation is still in progress. Optional filters select lifecycle states and storage phases.

This endpoint accepts no request body.

NameInTypeRequiredDescription
statequerystringNoComma-separated lifecycle states to keep, case-insensitive. For example, state=running or state=Failed,Orphaned. A VM that has no state yet counts as Creating. An unrecognised value is refused with 400 SpecInvalid.
phasequerystringNoComma-separated storage phases to keep: committed or creating. An unrecognised value is refused with 400 SpecInvalid.

Media type: application/json

Returns every known VM, including creates still in progress.

Response fields

FieldTypeRequiredDescription
[]arrayYesArray of VM summaries.
[].namestringYesVM name.
[].vm_idstringNoVM identifier.
[].phasestringYesStorage phase, either committed or creating.
[].statestringNoLifecycle state. A VM without a state counts as Creating.
[].shareobjectNoDisk usage for the VM’s share/ folder. It is absent until a measurement has completed, which does not mean the folder is empty.
[].share.bytesintegerYes, when share is presentAllocated size in bytes. Reflinked data shared with the VM disk can be counted in both places, while a hard-linked file is counted once.
[].share.partialbooleanYes, when share is presentWhether the measurement stopped early. When true, bytes is a lower bound rather than a total.
[].share.sampled_unixintegerYes, when share is presentTime of the measurement in Unix seconds.
[].share.quota_bytesintegerNoCurrent share quota in bytes. It is absent when the share has no limit.
[].share.over_quotabooleanYes, when share is presentLatched state left by the last quota crossing, not a comparison with the latest measurement. It becomes true when a measurement exceeds the quota, including a partial measurement. It becomes false only when a complete measurement is at or below quota - quota / 16, with integer division rounded down, or when the quota is removed. It can remain true below the quota. Changing the quota re-checks the last measurement and can change this state. Each change publishes one share-quota event. It is always false when there is no quota.
[
{
"name": "dev-vm",
"vm_id": "0000019a3f5c2e11",
"phase": "committed",
"state": "Running",
"share": {
"bytes": 3221225472,
"partial": false,
"sampled_unix": 1767225600,
"quota_bytes": 10737418240,
"over_quota": false
}
},
{
"name": "web-01",
"vm_id": "0000019a3f5c2e13",
"phase": "committed",
"state": "Running",
"share": {
"bytes": 1073741824,
"partial": false,
"sampled_unix": 1767225600,
"quota_bytes": 10737418240,
"over_quota": false
}
}
]
Terminal window
curl --request GET \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms?state=Running&phase=committed'

GET /api/v1/vm/vms/{name}

Returns the VM’s current state, committed configuration, share measurement, and create progress when creation is still in progress.

This endpoint accepts no request body.

NameInTypeRequiredDescription
namepathstringYesVM name. It must contain lowercase letters, digits, and -, begin with a letter or digit, and be at most 63 characters long.

Media type: application/json

Returns the VM’s current state, its configuration, and, while it is being created, create progress.

Response fields

FieldTypeRequiredDescription
namestringYesVM name.
vm_idstringNoVM identifier.
statestringYesLifecycle state: Creating, Stopped, Starting, Running, Paused, Stopping, Failed, or Orphaned.
reasonstringNoProse reason for the current state.
runstringNoIdentifier of the current run.
progressobjectNoCreate progress.
progress.phasestringYes, when progress is presentCreate phase: reserving, importing, committing, committed, or failed.
progress.bytes_doneintegerYes, when progress is presentBytes processed so far.
progress.bytes_totalintegerYes, when progress is presentTotal bytes to process.
progress.fell_backstringNoSet when reflink cloning was unavailable and the disk was fully copied instead.
progress.warningsarray of stringNoWarnings about a create that succeeded, such as an identity or TPM difference introduced by cloning.
progress.errorobjectNoPresent when progress.phase is failed. It contains the background create failure.
progress.error.errorobjectYes, when progress.error is presentNested error envelope.
progress.error.error.codestringYes, when progress.error is presentError code.
progress.error.error.messagestringYes, when progress.error is presentHuman-readable explanation.
progress.error.error.retryablebooleanYes, when progress.error is presentWhether repeating the identical request could succeed without any other change.
sidecarsarrayNoHealth of the VM’s helper processes. It is omitted when empty.
sidecars[].kindstringYesHelper kind: passt, virtiofsd, or swtpm.
sidecars[].statestringYesHelper state: absent, starting, ready, degraded, or stopped.
specobjectNoCommitted VM configuration. It can be absent during creation, when it cannot be read, or when it changed during four consecutive reads. Read again in that case.
spec.memory_mibintegerYes, when spec is presentGuest RAM in MiB.
spec.vcpusintegerYes, when spec is presentNumber of virtual CPUs.
spec.disk_bytesintegerNoSystem disk size in bytes. It is absent when the size cannot be read.
spec.firmwarestringYes, when spec is presentFirmware: uefi, uefi-secure-boot, or bios.
spec.busstringYes, when spec is presentSystem disk controller: virtio or sata.
spec.display_adapterstringYes, when spec is presentGuest display adapter: vga or virtio-vga. It is fixed when the VM is created, and new VMs use virtio-vga.
spec.cpustringYes, when spec is presentCPU model: qemu-default, westmere, or host. The portable creation setting produces westmere.
spec.tpmbooleanYes, when spec is presentWhether the VM has a TPM 2.0.
spec.file_sharingbooleanYes, when spec is presentWhether the share/ folder is shared into the guest.
spec.agentbooleanYes, when spec is presentWhether the guest-agent channel is configured.
spec.consolebooleanYes, when spec is presentWhether the serial console is configured.
spec.console_inputbooleanYes, when spec is presentWhether console input is allowed.
spec.audiostringYes, when spec is presentAudio device: none or output.
spec.machine_typestringYes, when spec is presentQEMU machine type to which the VM is pinned.
spec.displayintegerNoX display number. It is absent when the VM is headless.
spec.cdromsarray of string or nullNoAttached read-only media in boot order. A null value is an empty slot.
spec.autostartbooleanYes, when spec is presentWhether the VM starts automatically with the service.
spec.disk_bpsintegerNoDisk throughput limit in bytes per second. It is absent when unlimited.
spec.disk_iopsintegerNoDisk operations-per-second limit. It is absent when unlimited.
spec.share_quota_bytesintegerNoShare quota in bytes. It is absent when unlimited and is checked only when the VM starts.
spec.portsarrayNoInbound port forwards. It is absent when the VM accepts no inbound connections.
spec.ports[].protostringNoTransport protocol: tcp or udp. Default: "tcp".
spec.ports[].hostintegerYesPort opened on the computer’s addresses. It is shared by every VM in the computer.
spec.ports[].guestintegerYesPort on which the guest listens.
spec.stop_grace_secondsintegerNoHow long a graceful stop waits before forcing the VM off, in seconds. It is absent when the default of 30 applies.
display_urlstringNoBrowser address of the VM’s display. It is present when the VM has a display and the request arrived through the computer’s VM URL.
monitor_stalledbooleanNoWhether the QMP monitor has stopped answering. It is omitted when false.
seqintegerNoVM event counter as of this response. It is absent when no events have been published for the VM.
errorobjectNoTyped reason the current run failed. The code is nested at error.error.code.
error.errorobjectYes, when error is presentNested error envelope.
error.error.codestringYes, when error is presentError code.
error.error.messagestringYes, when error is presentHuman-readable explanation.
error.error.retryablebooleanYes, when error is presentWhether repeating the identical request could succeed without any other change.
shareobjectNoDisk usage for the VM’s share/ folder. It is absent until a measurement has completed.
share.bytesintegerYes, when share is presentAllocated size in bytes. Data shared by reflink between share/ and the VM’s disk is counted in both, so this can exceed what deleting the share would free.
share.partialbooleanYes, when share is presentWhether the measurement stopped early. When true, bytes is a lower bound.
share.sampled_unixintegerYes, when share is presentTime of the measurement in Unix seconds.
share.quota_bytesintegerNoCurrent share quota in bytes.
share.over_quotabooleanYes, when share is presentLatched state left by the last quota crossing, not a comparison with the latest measurement. It becomes true when a measurement exceeds the quota, including a partial measurement. It becomes false only after a complete measurement is at or below quota - quota / 16, with integer division rounded down, or when the quota is removed. It can remain true below the quota. Changing the quota re-checks the last measurement and can change this state. Each change publishes one share-quota event. It is always false when there is no quota.

Sequence note: seq is the VM’s event counter on state frames. A per-VM resync uses data.detail.seq when the detail has one. Otherwise, for example during creation or when a resync carries data.error, it repeats the stream’s last known seq. That repeated value does not prove the current counter, so read the VM again. It 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 whatever its seq.

{
"name": "dev-vm",
"vm_id": "0000019a3f5c2e11",
"state": "Stopped",
"progress": {
"phase": "committed",
"bytes_done": 68719476736,
"bytes_total": 68719476736,
"warnings": []
},
"sidecars": [
{
"kind": "passt",
"state": "ready"
},
{
"kind": "virtiofsd",
"state": "ready"
},
{
"kind": "swtpm",
"state": "ready"
}
],
"spec": {
"memory_mib": 4096,
"vcpus": 4,
"disk_bytes": 68719476736,
"firmware": "uefi",
"bus": "virtio",
"display_adapter": "virtio-vga",
"cpu": "westmere",
"tpm": true,
"file_sharing": true,
"agent": true,
"console": true,
"console_input": true,
"audio": "none",
"machine_type": "q35",
"display": 7,
"autostart": false,
"disk_bps": 104857600,
"disk_iops": 1000,
"share_quota_bytes": 10737418240,
"ports": [
{
"proto": "tcp",
"host": 2222,
"guest": 22
}
],
"stop_grace_seconds": 60
},
"display_url": "https://{projectId}-{computerId}-display-7.{server}.computers.hoody.com",
"seq": 12,
"share": {
"bytes": 3221225472,
"partial": false,
"sampled_unix": 1767225600,
"quota_bytes": 10737418240,
"over_quota": false
}
}
Terminal window
curl --request GET \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm'

GET /api/v1/vm/vms/{name}/display

Opens the VM’s screen in the browser. The route redirects to the computer’s display-N URL for the number in the VM’s spec.display, on the same server and domain as the request. With format=json it answers 200 with the VM’s name, its display number and that address instead.

The address is built from the URL the request arrived on, each time, and is never stored: call this route through the computer’s vm URL. When the request did not arrive through the computer’s vm URL, and for display 0, which has no browser address, there is no address: the redirect is refused with 400 SpecInvalid, and the JSON answer omits url but still carries display.

The address opens the computer’s display service, which applies its own access rules: being allowed to call this route does not grant access to the display, and the address carries no credentials. This route starts nothing. The page shows the VM while the VM is running; starting the VM starts its display if nothing is running on it.

This endpoint accepts no request body.

NameInTypeRequiredDescription
namepathstringYesThe VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters.
formatquerystringNojson answers 200 with {name, display, url} instead of redirecting. Absent: redirect. Any other value is refused with 400 SpecInvalid.

Media type: application/json

With format=json: the VM’s display number and its browser address. The answer carries name and display, and url when the VM has a browser address.

Response fields

FieldTypeRequiredDescription
namestringYesVM name.
displayintegerYesThe VM’s X display number, as in spec.display.
urlstringNoBrowser address of that display. It is omitted when the request did not arrive through the computer’s vm URL, or for display 0, which has no browser address.
{
"name": "dev-vm",
"display": 7,
"url": "https://{projectId}-{computerId}-display-7.{server}.computers.hoody.com"
}
Terminal window
curl --request GET \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/display'

Add ?format=json to the query to receive the JSON answer instead of the redirect.

POST /api/v1/vm/vms

Creates a VM from a template, blank disk, ISO, offline disk image, existing VM disk, or snapshot artifact.

NameTypeRequiredDescription
namestringYesVM name. It must match ^[a-z0-9][a-z0-9-]{0,62}$.
sourceobjectYesTagged disk source. Its type must be one of the six values in the source union below.
memory_mibintegerYesGuest RAM in MiB. Minimum: 1. It is required even for a snapshot-artifact source because an artifact does not record sizing.
vcpusintegerYesNumber of virtual CPUs. Minimum: 1, maximum: 4096. It is required even for a snapshot-artifact source.
firmwarestringNoFirmware: uefi or bios. Default: "uefi". It is fixed at creation. With a snapshot-artifact source, the artifact’s firmware is used. A matching value is accepted, but bios against a UEFI artifact is refused.
busstringNoSystem disk controller: virtio or sata. Default: "virtio", except with a windows-* os on a host without the virtio-win driver ISO, where it is sata. It is fixed at creation. With a snapshot-artifact source, bus must be explicitly set. It must be the bus on which the guest was installed, because the wrong bus can leave the guest unable to boot and cannot be changed later. Omitting it for this source is refused with 400.
displayinteger or stringNoX display from 0 to 65535. The forms 7, "7", and ":7" select the same display. "auto" selects the lowest free display in the automatic range. Omitting it creates a headless VM.
display_idinteger or stringNoAnother name for display, with the same values and meaning, including "auto". Send either field. If both are sent, they must have the same value.
cpustringNoCPU model: portable or host. Default: "portable". portable uses Westmere and produces a consistent CPU identity across hosts. host exposes the physical CPU. It is fixed at creation and refused with a snapshot-artifact source.
agentbooleanNoWhether to configure the guest-agent channel. Default: true. It is fixed at creation. A snapshot-artifact source determines this setting.
consolebooleanNoWhether to configure a serial console. Default: true. It is fixed at creation. A snapshot-artifact source determines this setting.
console_inputbooleanNoWhether the console accepts input. It defaults to the value of console, and true is refused unless console is also true. With a snapshot-artifact source, it defaults to the artifact’s console setting and is checked against it.
audiostringNoAudio configuration: none or output. Default: "none". output requires a display and host audio support. It is fixed at creation. With a snapshot-artifact source, the artifact’s sound card is used. A matching value is accepted, but output against an artifact without a sound card is refused.
sharebooleanNoWhether to share the VM’s share/ folder into the guest. Default: false. It is fixed at creation and requires host file-sharing support. A snapshot-artifact source determines this setting.
osstringNoGuest operating system: windows-11, windows-server, or linux. It selects operating-system-specific firmware, Secure Boot, TPM and disk bus defaults. A windows-* preset uses virtio, except on a host with no virtio-win driver ISO, where it gives the VM a sata system disk and the create carries a warning saying so; the bus is fixed at creation. Any explicitly supplied field takes precedence. A snapshot-artifact source refuses this field.
secure_bootbooleanNoWhether Secure Boot is active. Default when os is omitted: false; the windows-11 preset turns it on. It requires firmware: "uefi" and host Secure Boot support. It is fixed at creation and refused with a snapshot-artifact source.
disk_bpsintegerNoDisk throughput limit in bytes per second for all attached disks and CD-ROMs combined. Minimum: 65536. Omitting it means unlimited. It does not limit shared-folder traffic.
disk_iopsintegerNoDisk operations-per-second limit for all attached disks and CD-ROMs combined. Minimum: 8. Omitting it means unlimited. It does not limit shared-folder traffic.
share_quota_bytesintegerNoSize limit in bytes for the VM’s share/ folder. Minimum: 1. Omitting it means unlimited. A limit on a VM without share is refused. The limit is checked when the VM starts: a share measured over the limit is refused with 507 InsufficientSpace, and the check is skipped if the folder cannot be measured. It is not a hard limit while the VM runs. over_quota is the latched state left by the last quota crossing, not a comparison with the latest measurement. It becomes true when a measurement exceeds the quota, including a partial measurement. It becomes false only when a complete measurement is at or below quota - quota / 16, with integer division rounded down, or when the quota is removed. Changing the quota re-checks the last measurement and can change this state. Each change publishes one share-quota event. It is always false when there is no quota.
portsarrayNoInbound port forwards. The array can contain at most 128 entries. Omitting it or passing an empty array makes the VM outbound-only.
autostartbooleanNoWhether the VM starts automatically when the service starts. Default: false.
tpmbooleanNoWhether to provide a TPM 2.0. When os is omitted, omitting it enables the TPM when the host supports it; the windows-* presets turn it on and linux turns it off. The TPM is fixed at creation and cannot later be replaced by a different TPM. A snapshot-artifact source refuses this field.
stop_grace_secondsintegerNoHow long a graceful stop waits for the guest to power itself down before forcing it off, from 5 to 900 seconds. Omitting it uses the default of 30. It is mutable only while the VM is stopped.

The source object is a tagged union on type. Each variant requires its own fields and rejects fields belonging to other variants.

typeRequired fieldsDescription
templatetype, idCreates the VM from a template catalog entry. Templates include the guest drivers required by the selected operating system.
blanktype, gibCreates a VM with an empty, sparsely allocated disk of the requested size in GiB.
isotype, gib, and exactly one of sha256 or pathInstalls from an ISO onto a new disk. A url is refused. Download the image into the ISO store first, then create the VM from its sha256.
offline-filetype, pathCopies an existing host disk image into the VM. The source can be removed after the copy completes.
vm-disktype, nameClones the disk of an existing VM. The source VM must not be running. The clone receives a new identity and a new TPM.
snapshot-artifacttype, sha256, plus the top-level busRebuilds a VM from a snapshot artifact. The artifact provides the disk, firmware, TPM state, CPU model, machine profile, and other hardware. bus must be explicitly supplied because the artifact does not record it. It must match the bus on which the guest was installed, since the wrong bus can leave the guest unable to boot and cannot be changed later. Omitting bus is refused with 400. For every artifact carrying TPM state, including every Windows 11 guest, duplicate_tpm_identity must be explicitly set to true; omitting it is refused with 400. The acknowledgement means the copy holds the same TPM identity and sealed keys as the original.
Source fieldApplies toTypeRequiredDescription
source.idtemplatestringYesTemplate catalog identifier.
source.gibblank, isointegerYesDisk size in GiB. Minimum: 1, maximum: 16384. For a blank disk, the allocation is sparse, but this is the size seen by the guest.
source.sha256isostringConditionallySHA-256 identifier of an image in the ISO store. It must contain exactly 64 lowercase hexadecimal characters. This is the preferred ISO form because the store verifies the image contents. An upload that is still in progress is refused.
source.sha256snapshot-artifactstringYesSHA-256 identifier of a finalized artifact in the import store. It must contain exactly 64 lowercase hexadecimal characters. The artifact keeps its recorded disk size, so this source has no gib field.
source.pathisostringConditionallyAbsolute path to an installer ISO already on the host. The ISO is used in place, so the file must exist at every VM start, not only at creation. Its contents are not verified.
source.pathoffline-filestringYesAbsolute path to a disk image already on the host. The image is copied into the VM, and its contents are not verified.
source.urlisostringNoA URL is not accepted. Download the image into the ISO store first, then create the VM from its sha256.
source.namevm-diskstringYesName of the existing VM whose disk is cloned. The source must not be running.
source.duplicate_tpm_identitysnapshot-artifactbooleanConditionallyDefault: false. Every artifact carrying TPM state, including every Windows 11 guest, requires this field to be explicitly set to true; omission is refused with 400. Setting it acknowledges that the copy holds the same TPM identity and sealed keys as the original. Two live copies can therefore unseal each other’s secrets. Setting it for an artifact without TPM state has no effect.

With a snapshot-artifact source, os, tpm, secure_boot, share, agent, cpu, and console are refused because the artifact already defines that hardware. firmware and audio are refused only when they contradict the artifact: firmware: "bios" for an artifact installed under UEFI, or audio: "output" for one with no sound device. Their defaults, uefi and none, count as omitted, and the artifact’s values apply. The artifact does not record memory_mib, vcpus, display, autostart, disk_bps, disk_iops, share_quota_bytes, or bus, so those values come from the request. Grow the artifact’s disk afterwards with the Reconfigure a stopped VM operation.

NameTypeRequiredDescription
protostringNoTransport protocol: tcp or udp. Default: "tcp". TCP and UDP forwards are separate.
hostintegerYesPort opened on the computer’s addresses, from 1 to 65535. Host ports are shared by every VM in the computer, including stopped VMs. The port must be at or above the current unprivileged port threshold, which is 1024 when no lower threshold is configured.
guestintegerYesPort on which the guest listens, from 1 to 65535. It is not shared between VMs.
{
"name": "dev-vm",
"source": {
"type": "blank",
"gib": 64
},
"memory_mib": 4096,
"vcpus": 4,
"display_id": 7,
"os": "linux",
"tpm": true,
"share": true,
"share_quota_bytes": 10737418240,
"ports": [
{
"proto": "tcp",
"host": 2222,
"guest": 22
}
],
"stop_grace_seconds": 60
}

Media type: application/json

The create was accepted and continues in the background. Use the Location response header with the Get a VM operation, and poll until progress.phase is committed or failed. A failure decided in the background appears in progress.error, not as this operation’s status.

Response fields

FieldTypeRequiredDescription
namestringYesName of the VM being created.
vm_idstringYesIdentifier assigned to the VM.
statestringYesInitial VM state.
displayintegerNoX display number selected for the VM, including one selected by display: "auto". It is absent when the VM is headless.

The Location response header contains the URL to poll for create progress.

{
"name": "dev-vm",
"vm_id": "0000019a3f5c2e11",
"state": "Creating",
"display": 7
}

Errors reported in progress.error

progress.error has the same envelope as an HTTP error body. These codes arrive only there:

Error CodeTitleDescriptionResolution
NotFoundSource VM not foundThe vm-disk source VM does not exist.Check the source VM name.
SourceBusySource is busy or changedThe source VM is running or its state cannot be confirmed as stopped. For an offline-file source, the path may also have changed what it points to while the create was starting, either to a different VM’s disk or into or out of a VM’s storage.Read the error message to see which case applies. Stop the source VM if it is running. For an offline-file source, check what the path points to. Then retry the create.
InsufficientSpaceInsufficient storage spaceThe disk does not fit. The error carries need and have in bytes.Free storage space or request a smaller disk.

SpecInvalid, PortForwardConflict and StorageFailed can arrive either as this call’s status or in progress.error.

Terminal window
curl --request POST \
--header 'Content-Type: application/json' \
--data '{
"name": "dev-vm",
"source": {
"type": "blank",
"gib": 64
},
"memory_mib": 4096,
"vcpus": 4,
"display_id": 7,
"os": "linux",
"tpm": true,
"share": true,
"share_quota_bytes": 10737418240,
"ports": [
{
"proto": "tcp",
"host": 2222,
"guest": 22
}
],
"stop_grace_seconds": 60
}' \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms'

PATCH /api/v1/vm/vms/{name}

Changes the mutable configuration of a stopped VM. The VM must be stopped and must not have another operation in progress. Changes take effect at the next start.

At least one field is required: an empty object is refused with 400 SpecInvalid. Omitted fields remain unchanged. display: null makes the VM headless, cdroms: [] ejects every disc, and ports: [] removes every port forward. ports: null is an error.

disk_gib grows the system disk to an absolute size. It cannot be combined with any other field and must be sent in a separate request. The guest must still extend its partition and filesystem after the disk grows.

The following fields are fixed for the life of the VM: firmware, secure_boot, machine_type, tpm, cpu, agent, audio, console, console_input, share, bus, display_adapter, and name.

NameInTypeRequiredDescription
namepathstringYesVM name. It must contain lowercase letters, digits, and -, begin with a letter or digit, and be at most 63 characters long.
NameTypeRequiredDescription
memory_mibintegerNoGuest RAM in MiB from the next start. Minimum: 1. Host capacity is checked at the next start, not when the change is saved.
vcpusintegerNoNumber of virtual CPUs from the next start. Minimum: 1, maximum: 4096.
disk_gibintegerNoGrow the system disk to this absolute size in GiB. Minimum: 1, maximum: 16384. The current size is a no-op, and a smaller size is refused. This field must be sent alone.
displayinteger or string or nullNoMove the VM to an X display from 0 to 65535, or use null to make it headless. null is refused when spec.audio is output.
display_idinteger or string or nullNoAnother name for display with the same values and meaning. Send either field. If both are sent, they must have the same value.
cdromsarray of string or nullNoReplace the attached media in boot order. [] ejects everything. Each path must be absolute and must exist. The array can contain at most six entries, or five when the system disk uses sata.
autostartbooleanNoWhether the VM starts automatically when the service starts.
disk_bpsinteger or nullNoDisk throughput limit in bytes per second. Minimum: 65536. null removes the limit, and omitting it leaves the current value unchanged. It does not limit shared-folder traffic.
disk_iopsinteger or nullNoDisk operations-per-second limit. Minimum: 8. null removes the limit, and omitting it leaves the current value unchanged. It does not limit shared-folder traffic.
share_quota_bytesinteger or nullNoSize limit in bytes for the VM’s share/ folder. Minimum: 1. null removes the limit, and omitting it leaves the current value unchanged. The limit is checked when the VM starts: a share measured over the limit is refused with 507 InsufficientSpace, and the check is skipped if the folder cannot be measured. It is not a hard limit while the VM runs. over_quota is the latched state left by the last quota crossing, not a comparison with the latest measurement. It becomes true when a measurement exceeds the quota, including a partial measurement. It becomes false only when a complete measurement is at or below quota - quota / 16, with integer division rounded down, or when the quota is removed. Changing the quota re-checks the last measurement and can change this state. Each change publishes one share-quota event. It is always false when there is no quota. Removing the quota from a VM that is over it clears over_quota and publishes one share-quota event.
portsarrayNoReplace all inbound port forwards with this list. Omitting it leaves the rules unchanged, [] removes every rule and makes the VM outbound-only, and null is refused. The array can contain at most 128 entries. A host port already declared by another VM is refused with 409 PortForwardConflict.
stop_grace_secondsinteger or nullNoHow long a graceful stop waits for the guest to power itself down before forcing it off, from 5 to 900 seconds. null restores the default of 30, and omitting it leaves the current value unchanged.

Each port forward uses the proto, host, and guest fields documented under Create a VM.

{
"memory_mib": 6144,
"vcpus": 4,
"display": null,
"cdroms": [],
"disk_bps": 104857600,
"disk_iops": 1000,
"share_quota_bytes": 10737418240,
"ports": [],
"stop_grace_seconds": 60
}

Media type: application/json

Returns the VM’s configuration after the change, together with any warnings.

Response fields

FieldTypeRequiredDescription
namestringYesVM name.
vm_idstringYesVM identifier.
specobjectYesUpdated VM configuration.
spec.memory_mibintegerYesGuest RAM in MiB.
spec.vcpusintegerYesNumber of virtual CPUs.
spec.disk_bytesintegerNoSystem disk size in bytes.
spec.firmwarestringYesFirmware: uefi, uefi-secure-boot, or bios.
spec.busstringYesSystem disk controller: virtio or sata.
spec.display_adapterstringYesGuest display adapter: vga or virtio-vga. It is fixed when the VM is created.
spec.cpustringYesCPU model: qemu-default, westmere, or host.
spec.tpmbooleanYesWhether the VM has a TPM 2.0.
spec.file_sharingbooleanYesWhether the share/ folder is shared into the guest.
spec.agentbooleanYesWhether the guest-agent channel is configured.
spec.consolebooleanYesWhether the serial console is configured.
spec.console_inputbooleanYesWhether console input is allowed.
spec.audiostringYesAudio device: none or output.
spec.machine_typestringYesQEMU machine type to which the VM is pinned.
spec.displayintegerNoX display number. It is absent when the VM is headless.
spec.cdromsarray of string or nullNoAttached read-only media in boot order. A null value is an empty slot.
spec.autostartbooleanYesWhether the VM starts automatically with the service.
spec.disk_bpsintegerNoDisk throughput limit in bytes per second. It is absent when unlimited.
spec.disk_iopsintegerNoDisk operations-per-second limit. It is absent when unlimited.
spec.share_quota_bytesintegerNoShare quota in bytes. It is checked only when the VM starts.
spec.portsarrayNoInbound port forwards.
spec.ports[].protostringNoTransport protocol: tcp or udp. Default: "tcp".
spec.ports[].hostintegerYesPort opened on the computer’s addresses.
spec.ports[].guestintegerYesPort on which the guest listens.
spec.stop_grace_secondsintegerNoHow long a graceful stop waits before forcing the VM off, in seconds. It is absent when the default of 30 applies.
warningsarray of stringNoDetails about changes that succeeded, such as devices added to the guest when a display was enabled.
{
"name": "dev-vm",
"vm_id": "0000019a3f5c2e11",
"spec": {
"memory_mib": 6144,
"vcpus": 4,
"disk_bytes": 68719476736,
"firmware": "uefi",
"bus": "virtio",
"display_adapter": "virtio-vga",
"cpu": "westmere",
"tpm": true,
"file_sharing": true,
"agent": true,
"console": true,
"console_input": true,
"audio": "none",
"machine_type": "q35",
"autostart": false,
"disk_bps": 104857600,
"disk_iops": 1000,
"share_quota_bytes": 10737418240,
"stop_grace_seconds": 60
},
"warnings": []
}
Terminal window
curl --request PATCH \
--header 'Content-Type: application/json' \
--data '{
"memory_mib": 6144,
"vcpus": 4,
"display": null,
"cdroms": [],
"disk_bps": 104857600,
"disk_iops": 1000,
"share_quota_bytes": 10737418240,
"ports": [],
"stop_grace_seconds": 60
}' \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm'

Change the disc in a running VM’s CD-ROM slot

Section titled “Change the disc in a running VM’s CD-ROM slot”

PUT /api/v1/vm/vms/{name}/cdroms/{slot}

Replaces the disc in one CD-ROM slot of a running or paused VM. The operation uses QEMU’s blockdev-change-medium and opens the source as a raw read-only image without probing its format.

The VM’s cdroms records the new disc before QEMU opens it. If QEMU refuses the change, the previous disc is restored. Only a slot that held a disc when the VM started has a drive in the current run. Filling a slot that was empty at start is refused until the next start; configure it with the Reconfigure a stopped VM operation while the VM is stopped.

The call returns after QEMU answers, within the monitor command deadline of 10 seconds.

NameInTypeRequiredDescription
namepathstringYesThe VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters.
slotpathintegerYesThe CD-ROM slot, counted from 0 in the order of the VM’s cdroms. Slot 0 is the one the VM boots from.
NameTypeRequiredDescription
sourcestringYesAbsolute path of the disc image to put in the slot. It must exist, be a regular file, and not be part of another VM’s storage. A file in this VM’s shared folder is allowed. It is opened as a raw image without probing its format.

Media type: application/json

QEMU opened the disc in the slot, and spec.cdroms names it.

Response fields

FieldTypeRequiredDescription
namestringYesVM name.
vm_idstringNoVM identifier.
statestringYesLifecycle state: Creating, Stopped, Starting, Running, Paused, Stopping, Failed, or Orphaned.
reasonstringNoProse reason for the current state.
runstringNoIdentifier of the current run.
progressobjectNoCreate progress.
progress.phasestringYes, when progress is presentCreate phase: reserving, importing, committing, committed, or failed.
progress.bytes_doneintegerYes, when progress is presentBytes processed so far.
progress.bytes_totalintegerYes, when progress is presentTotal bytes to process.
progress.fell_backstringNoSet when reflink cloning was unavailable and the disk was fully copied instead.
progress.warningsarray of stringNoWarnings about a create that succeeded.
progress.errorobjectNoPresent when progress.phase is failed. It contains the background create failure.
progress.error.errorobjectYes, when progress.error is presentNested error envelope.
progress.error.error.codestringYes, when progress.error is presentError code.
progress.error.error.messagestringYes, when progress.error is presentHuman-readable explanation.
progress.error.error.retryablebooleanYes, when progress.error is presentWhether repeating the identical request could succeed without any other change.
sidecarsarrayNoHealth of the VM’s helper processes. It is omitted when empty.
sidecars[].kindstringYesHelper kind: passt, virtiofsd, or swtpm.
sidecars[].statestringYesHelper state: absent, starting, ready, degraded, or stopped.
specobjectNoCommitted VM configuration. It can be absent during creation or when it cannot be read.
spec.memory_mibintegerYes, when spec is presentGuest RAM in MiB.
spec.vcpusintegerYes, when spec is presentNumber of virtual CPUs.
spec.disk_bytesintegerNoSystem disk size in bytes.
spec.firmwarestringYes, when spec is presentFirmware: uefi, uefi-secure-boot, or bios.
spec.busstringYes, when spec is presentSystem disk controller: virtio or sata.
spec.display_adapterstringYes, when spec is presentGuest display adapter: vga or virtio-vga.
spec.cpustringYes, when spec is presentCPU model: qemu-default, westmere, or host.
spec.tpmbooleanYes, when spec is presentWhether the VM has a TPM 2.0.
spec.file_sharingbooleanYes, when spec is presentWhether the share/ folder is shared into the guest.
spec.agentbooleanYes, when spec is presentWhether the guest-agent channel is configured.
spec.consolebooleanYes, when spec is presentWhether the serial console is configured.
spec.console_inputbooleanYes, when spec is presentWhether console input is allowed.
spec.audiostringYes, when spec is presentAudio device: none or output.
spec.machine_typestringYes, when spec is presentQEMU machine type to which the VM is pinned.
spec.displayintegerNoX display number. It is absent when the VM is headless.
spec.cdromsarray of string or nullNoAttached read-only media in boot order. A null value is an empty slot.
spec.autostartbooleanYes, when spec is presentWhether the VM starts automatically with the service.
spec.disk_bpsintegerNoDisk throughput limit in bytes per second. It is absent when unlimited.
spec.disk_iopsintegerNoDisk operations-per-second limit. It is absent when unlimited.
spec.share_quota_bytesintegerNoShare quota in bytes. It is absent when unlimited and is checked only when the VM starts.
spec.portsarrayNoInbound port forwards.
spec.ports[].protostringNoTransport protocol: tcp or udp. Default: "tcp".
spec.ports[].hostintegerYesPort opened on the computer’s addresses.
spec.ports[].guestintegerYesPort on which the guest listens.
spec.stop_grace_secondsintegerNoHow long a graceful stop waits before forcing the VM off, in seconds. It is absent when the default of 30 applies.
display_urlstringNoBrowser address of the VM’s display.
monitor_stalledbooleanNoWhether the QMP monitor has stopped answering. It is omitted when false.
seqintegerNoVM event counter as of this response.
errorobjectNoTyped reason the current run failed. The code is nested at error.error.code.
error.errorobjectYes, when error is presentNested error envelope.
error.error.codestringYes, when error is presentError code.
error.error.messagestringYes, when error is presentHuman-readable explanation.
error.error.retryablebooleanYes, when error is presentWhether repeating the identical request could succeed without any other change.
shareobjectNoDisk usage for the VM’s share/ folder. It is absent until a measurement has completed.
share.bytesintegerYes, when share is presentAllocated size in bytes. Data shared by reflink between share/ and the VM’s disk is counted in both.
share.partialbooleanYes, when share is presentWhether the measurement stopped early. When true, bytes is a lower bound.
share.sampled_unixintegerYes, when share is presentTime of the measurement in Unix seconds.
share.quota_bytesintegerNoCurrent share quota in bytes.
share.over_quotabooleanYes, when share is presentLatched state left by the last quota crossing.
{
"name": "dev-vm",
"vm_id": "0000019a3f5c2e11",
"state": "Running",
"spec": {
"memory_mib": 6144,
"vcpus": 4,
"disk_bytes": 68719476736,
"firmware": "uefi",
"bus": "virtio",
"display_adapter": "virtio-vga",
"cpu": "westmere",
"tpm": true,
"file_sharing": true,
"agent": true,
"console": true,
"console_input": true,
"audio": "none",
"machine_type": "q35",
"cdroms": [
"/opt/images/dev-installer.iso"
],
"autostart": false,
"disk_bps": 104857600,
"disk_iops": 1000,
"share_quota_bytes": 10737418240,
"stop_grace_seconds": 60
},
"share": {
"bytes": 3221225472,
"partial": false,
"sampled_unix": 1767225600,
"quota_bytes": 10737418240,
"over_quota": false
}
}
Terminal window
curl --request PUT \
--header 'Content-Type: application/json' \
--data '{
"source": "/opt/images/dev-installer.iso"
}' \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/cdroms/0'

Eject the disc from a running VM’s CD-ROM slot

Section titled “Eject the disc from a running VM’s CD-ROM slot”

DELETE /api/v1/vm/vms/{name}/cdroms/{slot}

Ejects the disc from one CD-ROM slot of a running or paused VM using QEMU’s eject operation. The ejection is never forced. If the guest has locked the tray, QEMU refuses the operation and asks the guest to release it. Try again after the guest releases it.

The slot remains in place and becomes empty. The VM’s cdroms shows null for it only after QEMU has ejected the disc. Ejecting an empty slot succeeds without changing anything.

The call returns after QEMU answers, within the monitor command deadline of 10 seconds.

This endpoint accepts no request body.

NameInTypeRequiredDescription
namepathstringYesThe VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters.
slotpathintegerYesThe CD-ROM slot, counted from 0 in the order of the VM’s cdroms. Slot 0 is the one the VM boots from.

Media type: application/json

The slot is empty, and spec.cdroms shows null for it.

Response fields

FieldTypeRequiredDescription
namestringYesVM name.
vm_idstringNoVM identifier.
statestringYesLifecycle state: Creating, Stopped, Starting, Running, Paused, Stopping, Failed, or Orphaned.
reasonstringNoProse reason for the current state.
runstringNoIdentifier of the current run.
progressobjectNoCreate progress.
progress.phasestringYes, when progress is presentCreate phase: reserving, importing, committing, committed, or failed.
progress.bytes_doneintegerYes, when progress is presentBytes processed so far.
progress.bytes_totalintegerYes, when progress is presentTotal bytes to process.
progress.fell_backstringNoSet when reflink cloning was unavailable and the disk was fully copied instead.
progress.warningsarray of stringNoWarnings about a create that succeeded.
progress.errorobjectNoPresent when progress.phase is failed. It contains the background create failure.
progress.error.errorobjectYes, when progress.error is presentNested error envelope.
progress.error.error.codestringYes, when progress.error is presentError code.
progress.error.error.messagestringYes, when progress.error is presentHuman-readable explanation.
progress.error.error.retryablebooleanYes, when progress.error is presentWhether repeating the identical request could succeed without any other change.
sidecarsarrayNoHealth of the VM’s helper processes. It is omitted when empty.
sidecars[].kindstringYesHelper kind: passt, virtiofsd, or swtpm.
sidecars[].statestringYesHelper state: absent, starting, ready, degraded, or stopped.
specobjectNoCommitted VM configuration. It can be absent during creation or when it cannot be read.
spec.memory_mibintegerYes, when spec is presentGuest RAM in MiB.
spec.vcpusintegerYes, when spec is presentNumber of virtual CPUs.
spec.disk_bytesintegerNoSystem disk size in bytes.
spec.firmwarestringYes, when spec is presentFirmware: uefi, uefi-secure-boot, or bios.
spec.busstringYes, when spec is presentSystem disk controller: virtio or sata.
spec.display_adapterstringYes, when spec is presentGuest display adapter: vga or virtio-vga.
spec.cpustringYes, when spec is presentCPU model: qemu-default, westmere, or host.
spec.tpmbooleanYes, when spec is presentWhether the VM has a TPM 2.0.
spec.file_sharingbooleanYes, when spec is presentWhether the share/ folder is shared into the guest.
spec.agentbooleanYes, when spec is presentWhether the guest-agent channel is configured.
spec.consolebooleanYes, when spec is presentWhether the serial console is configured.
spec.console_inputbooleanYes, when spec is presentWhether console input is allowed.
spec.audiostringYes, when spec is presentAudio device: none or output.
spec.machine_typestringYes, when spec is presentQEMU machine type to which the VM is pinned.
spec.displayintegerNoX display number. It is absent when the VM is headless.
spec.cdromsarray of string or nullNoAttached read-only media in boot order. A null value is an empty slot.
spec.autostartbooleanYes, when spec is presentWhether the VM starts automatically with the service.
spec.disk_bpsintegerNoDisk throughput limit in bytes per second. It is absent when unlimited.
spec.disk_iopsintegerNoDisk operations-per-second limit. It is absent when unlimited.
spec.share_quota_bytesintegerNoShare quota in bytes. It is absent when unlimited and is checked only when the VM starts.
spec.portsarrayNoInbound port forwards.
spec.ports[].protostringNoTransport protocol: tcp or udp. Default: "tcp".
spec.ports[].hostintegerYesPort opened on the computer’s addresses.
spec.ports[].guestintegerYesPort on which the guest listens.
spec.stop_grace_secondsintegerNoHow long a graceful stop waits before forcing the VM off, in seconds. It is absent when the default of 30 applies.
display_urlstringNoBrowser address of the VM’s display.
monitor_stalledbooleanNoWhether the QMP monitor has stopped answering. It is omitted when false.
seqintegerNoVM event counter as of this response.
errorobjectNoTyped reason the current run failed. The code is nested at error.error.code.
error.errorobjectYes, when error is presentNested error envelope.
error.error.codestringYes, when error is presentError code.
error.error.messagestringYes, when error is presentHuman-readable explanation.
error.error.retryablebooleanYes, when error is presentWhether repeating the identical request could succeed without any other change.
shareobjectNoDisk usage for the VM’s share/ folder. It is absent until a measurement has completed.
share.bytesintegerYes, when share is presentAllocated size in bytes. Data shared by reflink between share/ and the VM’s disk is counted in both.
share.partialbooleanYes, when share is presentWhether the measurement stopped early. When true, bytes is a lower bound.
share.sampled_unixintegerYes, when share is presentTime of the measurement in Unix seconds.
share.quota_bytesintegerNoCurrent share quota in bytes.
share.over_quotabooleanYes, when share is presentLatched state left by the last quota crossing.
{
"name": "dev-vm",
"vm_id": "0000019a3f5c2e11",
"state": "Running",
"spec": {
"memory_mib": 6144,
"vcpus": 4,
"disk_bytes": 68719476736,
"firmware": "uefi",
"bus": "virtio",
"display_adapter": "virtio-vga",
"cpu": "westmere",
"tpm": true,
"file_sharing": true,
"agent": true,
"console": true,
"console_input": true,
"audio": "none",
"machine_type": "q35",
"cdroms": [
null
],
"autostart": false,
"disk_bps": 104857600,
"disk_iops": 1000,
"share_quota_bytes": 10737418240,
"stop_grace_seconds": 60
},
"share": {
"bytes": 3221225472,
"partial": false,
"sampled_unix": 1767225600,
"quota_bytes": 10737418240,
"over_quota": false
}
}
Terminal window
curl --request DELETE \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/cdroms/0'

DELETE /api/v1/vm/vms/{name}

Deletes a VM and its associated resources.

This endpoint accepts no request body.

NameInTypeRequiredDescription
namepathstringYesVM name. It must contain lowercase letters, digits, and -, begin with a letter or digit, and be at most 63 characters long.
forcequerybooleanNoforce, force=true, or force=1 deletes the VM even if it is running, stopping it first without asking the guest to shut down. If force is absent, false, or 0, a running VM is refused with 409 BadState. Any other value is refused with 400 SpecInvalid.

Media type: application/json

The VM was deleted.

Response fields

FieldTypeRequiredDescription
namestringYesName of the deleted VM.
deletedbooleanYesWhether the VM was deleted.
{
"name": "dev-vm",
"deleted": true
}
Terminal window
curl --request DELETE \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm?force=true'