VM: Lifecycle
Section titled “VM: Lifecycle”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.
Shared response fields
Section titled “Shared response fields”Every 200 response below uses the VM detail shape.
VM detail fields
Section titled “VM detail fields”| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | The VM name. |
vm_id | string | No | The VM identifier, represented by 16 lowercase hexadecimal digits. |
state | string | Yes | Current state: Creating, Stopped, Starting, Running, Paused, Stopping, Failed, or Orphaned. |
reason | string | No | Prose explanation of the current condition. A Failed VM without error carries only reason. |
run | string | No | Identifier for the current VM run. |
progress | object | No | Progress reported while the VM is being created. |
progress.phase | string | Yes | Progress phase: reserving, importing, committing, committed, or failed. |
progress.bytes_done | integer | Yes | Number of bytes processed. |
progress.bytes_total | integer | Yes | Total number of bytes to process. |
progress.fell_back | string | No | Set when the disk could not be cloned by reflink and was copied instead. |
progress.warnings | array | No | Warnings about a create that succeeded. |
progress.error | object | No | Present when progress.phase is failed. |
progress.error.error | object | Yes | Nested error envelope for the failed create. |
progress.error.error.code | string | Yes | Machine-readable error code. |
progress.error.error.message | string | Yes | Human-readable explanation. |
progress.error.error.retryable | boolean | Yes | Whether repeating the identical request could succeed without another change. |
sidecars | array | No | Health of the VM’s helper processes. Omitted when empty. |
sidecars[].kind | string | Yes | Helper kind: passt, virtiofsd, or swtpm. |
sidecars[].state | string | Yes | Helper state: absent, starting, ready, degraded, or stopped. |
spec | object | No | The 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_mib | integer | Yes | Guest RAM in MiB. Mutable while stopped. |
spec.vcpus | integer | Yes | Number of virtual CPUs. Mutable while stopped. |
spec.disk_bytes | integer | No | Size of the system disk in bytes. Mutable while stopped, grow only. |
spec.firmware | string | Yes | Firmware type: uefi, uefi-secure-boot, or bios. |
spec.bus | string | Yes | System disk controller: virtio or sata. |
spec.display_adapter | string | Yes | Display adapter: vga or virtio-vga. |
spec.cpu | string | Yes | CPU model: qemu-default, westmere, or host. |
spec.tpm | boolean | Yes | Whether the VM has a TPM 2.0. |
spec.file_sharing | boolean | Yes | Whether the VM’s share/ folder is shared into the guest. |
spec.agent | boolean | Yes | Whether the VM has the guest-agent channel. |
spec.console | boolean | Yes | Whether the VM has a serial console. |
spec.console_input | boolean | Yes | Whether console input can be written to the VM. |
spec.audio | string | Yes | Audio mode: none or output. |
spec.machine_type | string | Yes | The QEMU machine type assigned to the VM. |
spec.display | integer | No | X display number. Absent for a headless VM. |
spec.cdroms | array | No | Attached read-only media in boot order. |
spec.autostart | boolean | Yes | Whether the VM starts automatically when the service starts. |
spec.disk_bps | integer | No | Disk throughput limit in bytes per second. |
spec.disk_iops | integer | No | Disk operations per second limit. |
spec.share_quota_bytes | integer | No | Size limit in bytes for the VM’s share/ folder. Checked when the VM starts. |
spec.ports | array | No | Inbound port forwards. At most 128 rules can be configured. |
spec.ports[].proto | string | No | Transport protocol: tcp or udp. Default: "tcp". |
spec.ports[].host | integer | Yes | Port opened on the computer, from 1 through 65535. |
spec.ports[].guest | integer | Yes | Port the guest listens on, from 1 through 65535. |
spec.stop_grace_seconds | integer | No | How 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_url | string | No | Browser address of the VM’s screen. Present only in the getVm response when a display is configured. |
monitor_stalled | boolean | No | Indicates that the QMP monitor has stopped answering control commands. The VM can still read Running. |
seq | integer | No | The VM’s event counter as of the response. |
error | object | No | Nested error envelope for a failed run. The code is at error.error.code. |
error.error | object | Yes | Error details, present when error is present. |
error.error.code | string | Yes | Machine-readable error code. |
error.error.message | string | Yes | Human-readable explanation. |
error.error.retryable | boolean | Yes | Whether repeating the identical request could succeed without another change. |
share | object | No | Disk usage of the VM’s share/ folder. |
share.bytes | integer | Yes | Allocated size in bytes. |
share.partial | boolean | Yes | Whether the measurement stopped early, making bytes a lower bound. |
share.sampled_unix | integer | Yes | Measurement time in Unix seconds. |
share.quota_bytes | integer | No | Current quota in bytes. Absent when the share has no size limit. |
share.over_quota | boolean | Yes | Latched state from the last quota crossing. |
Error fields
Section titled “Error fields”HTTP error responses use this shape.
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | Error details. |
error.code | string | Yes | Machine-readable error code. Branch on this value rather than on error.message. |
error.message | string | Yes | Human-readable explanation. |
error.retryable | boolean | Yes | Whether repeating the identical request could succeed without another change. |
Sequence values
Section titled “Sequence values”seq is the VM’s event counter on state frames and in VM reads.
- A per-VM
resyncusesdata.detail.seqwhen the detail includes a sequence number. - If the detail has no
seq, such as a VM being created or aresynccarryingdata.error, theresyncrepeats the stream’s last knownseq. That repeated value does not prove the current counter, so re-read the VM. - The sequence number is
0on the all-VMs stream’sresync, on the uncounted kindsprogress,sidecar,qmp-error,snapshot,share-quota,monitor-stalled, anddeleted, and on thestateframe that ends a create. - Process every
resync, regardless of itsseq.
Shared-folder quota state
Section titled “Shared-folder quota state”share.over_quota is the latched state left by the last quota crossing. It is not a comparison with the latest measurement.
- It becomes
truewhen a measurement exceeds the quota. A partial measurement counts because its size is a lower bound. - It becomes
falseonly 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_quotacan remaintruebelow the quota within the hysteresis band. - Changing the quota rechecks the last measurement and can change the state.
- Each change of
over_quotapublishes oneshare-quotaevent. over_quotais alwaysfalsewhen there is no quota.
Start a VM
Section titled “Start a VM”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | Yes | The VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters. |
This endpoint does not accept a request body.
Request
Section titled “Request”curl --request POST \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/start'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const res = await client.vm.vms.start('dev-vm');const code = res.data.error?.error.code;Responses
Section titled “Responses”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 Code | Title | Description | Resolution |
|---|---|---|---|
SpecInvalid | Invalid start configuration | A 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. |
SourceBusy | Source is busy | A resource required by the start is currently busy. | Wait for the resource to become available and retry. |
KvmUnavailable | KVM unavailable | The computer cannot provide the required virtualization capability. | Check virtualization availability on the computer and retry. |
KvmCapExceeded | Computer KVM limit exceeded | The 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. |
MemoryExceedsCgroup | Memory limit exceeded | The VM’s memory requirement exceeds the available computer limit. | Reduce the requested memory or increase the computer’s limit, then retry. |
QemuExecFailed | QEMU execution failed | The service could not execute QEMU for the start. | Correct the launch problem reported by the service and retry. |
QemuExitedBeforeReady | QEMU exited before ready | QEMU exited before the VM became ready. | Inspect the VM run and service logs, correct the cause, and retry. |
QmpHandshakeFailed | QMP handshake failed | QEMU started, but its control handshake did not complete. | Inspect the launch failure, correct the control connection problem, and retry. |
StartupIndeterminate | Startup result indeterminate | The service could not determine the outcome of the launch. | Re-read the VM to establish whether it is Running or Failed before retrying. |
StorageFailed | Storage setup failed | The 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. |
JournalFailed | State persistence failed | The service could not persist the VM’s launch state. | Check service health, then retry after state persistence is available. |
DisplayUnavailable | Display unavailable | The configured display could not be provided for the VM. | Correct the display availability problem and retry. |
DisplayInUse | Display already in use | The display required by the VM is already in use. | Release the conflicting display assignment, then retry. |
SidecarUnavailable | Helper process unavailable | A 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. |
AudioBackendUnavailable | Audio backend unavailable | The configured audio backend could not be started. | Make an available audio backend available or use an audio configuration supported by the computer, then retry. |
TpmStateMissing | TPM state missing | The VM’s required TPM state is unavailable. | Correct the missing TPM state reported by the service and retry. |
Media type: application/json
The request name or specification is invalid.
{ "error": { "code": "NameInvalid", "message": "VM names must contain only lowercase letters, digits, and hyphens.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NameInvalid | Invalid VM name | The requested name does not match the required format. | Use a name containing only lowercase letters, digits, and -, starting with a letter or digit and no longer than 63 characters. |
SpecInvalid | Invalid request specification | The request specification is invalid, or the request contains query parameters even though this operation accepts none. | Correct the request specification and remove all query parameters. |
Media type: application/json
No VM has the requested name.
{ "error": { "code": "NotFound", "message": "No VM named dev-vm exists.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NotFound | VM not found | No VM has the requested name. | Verify the VM name and retry. |
Media type: application/json
The VM cannot accept the start command in its current state.
{ "error": { "code": "BadState", "message": "The VM is not in a state that supports this operation.", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BadState | Invalid VM state | The VM is not in a state to which this command applies. | Read the current VM state and retry only when the command applies. |
OperationInProgress | Another operation is running | Another create, start, stop, delete, or snapshot operation has not finished, or a newly created VM is not ready. | Poll getVm and retry after the current operation finishes. |
Orphaned | VM run cannot be managed | The service cannot verify or manage the VM run, and the guest may still be running. | For an unverifiable run, check the process and then use forceAdopt or forceMarkDead. For a blocked VM, resolve the condition named by the message and restart hoody-vm. |
Media type: application/json
The VM’s shared folder exceeds its quota, so nothing was started. The error carries need, the measured folder size in bytes, and have, the quota in bytes. If the measurement was partial, need is a lower bound rather than a complete total.
{ "error": { "code": "InsufficientSpace", "message": "The shared folder exceeds its quota.", "retryable": false, "need": 1073741824, "have": 536870912 }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
InsufficientSpace | Shared folder exceeds quota | The measured shared-folder size, reported as need, exceeds the quota, reported as have. | Reduce shared-folder usage or increase or remove the quota, then start the VM again. |
Stop a VM
Section titled “Stop a VM”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | Yes | The VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
grace_seconds | integer | No | How 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.
Request
Section titled “Request”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'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const res = await client.vm.vms.stop('dev-vm', { grace_seconds: 60 });const state = res.data.state;Responses
Section titled “Responses”Media type: application/json
The stop was accepted. Poll getVm until state is Stopped.
{ "name": "dev-vm", "vm_id": "0000019a3f5c2e11", "state": "Stopping", "seq": 42}Media type: application/json
The request name or specification is invalid.
{ "error": { "code": "NameInvalid", "message": "VM names must contain only lowercase letters, digits, and hyphens.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NameInvalid | Invalid VM name | The requested name does not match the required format. | Use a name containing only lowercase letters, digits, and -, starting with a letter or digit and no longer than 63 characters. |
SpecInvalid | Invalid request specification | The body is not valid JSON, carries an unknown field, or sets grace_seconds outside 5 through 900, or the request carries query parameters, which this operation does not accept. | Send a body with only grace_seconds between 5 and 900, or omit the body, and remove all query parameters. |
Media type: application/json
No VM has the requested name.
{ "error": { "code": "NotFound", "message": "No VM named dev-vm exists.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NotFound | VM not found | No VM has the requested name. | Verify the VM name and retry. |
Media type: application/json
The request body stopped arriving before the service could read it.
{ "error": { "code": "RequestBodyStalled", "message": "The request body stopped arriving.", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RequestBodyStalled | Request body stalled | The request body stopped arriving before the service could read it, so the stop was not carried out. | Send the request again with the complete body. |
Media type: application/json
The VM cannot accept the stop command in its current state.
{ "error": { "code": "BadState", "message": "The VM is not in a state that supports this operation.", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BadState | Invalid VM state | The VM is not in a state to which this command applies. | Read the current VM state and retry only when the command applies. |
OperationInProgress | Another operation is running | Another create, start, stop, delete, or snapshot operation has not finished, or a newly created VM is not ready. | Poll getVm and retry after the current operation finishes. |
Orphaned | VM run cannot be managed | The service cannot verify or manage the VM run, and the guest may still be running. | For an unverifiable run, check the process and then use forceAdopt or forceMarkDead. For a blocked VM, resolve the condition named by the message and restart hoody-vm. |
Force-stop a VM
Section titled “Force-stop a VM”POST /api/v1/vm/vms/{name}/force-stop
Force-stops a VM. Poll getVm until state is Stopped.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | Yes | The VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters. |
This endpoint does not accept a request body.
Request
Section titled “Request”curl --request POST \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/force-stop'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const res = await client.vm.vms.forceStop('dev-vm');const state = res.data.state;Responses
Section titled “Responses”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}Media type: application/json
The request name or specification is invalid.
{ "error": { "code": "NameInvalid", "message": "VM names must contain only lowercase letters, digits, and hyphens.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NameInvalid | Invalid VM name | The requested name does not match the required format. | Use a name containing only lowercase letters, digits, and -, starting with a letter or digit and no longer than 63 characters. |
SpecInvalid | Invalid request specification | The request contains query parameters even though this operation accepts none. | Remove all query parameters and retry. |
Media type: application/json
No VM has the requested name.
{ "error": { "code": "NotFound", "message": "No VM named dev-vm exists.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NotFound | VM not found | No VM has the requested name. | Verify the VM name and retry. |
Media type: application/json
The VM cannot accept the force-stop command in its current state.
{ "error": { "code": "BadState", "message": "The VM is not in a state that supports this operation.", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BadState | Invalid VM state | The VM is not in a state to which this command applies. | Read the current VM state and retry only when the command applies. |
OperationInProgress | Another operation is running | Another create, start, stop, delete, or snapshot operation has not finished, or a newly created VM is not ready. | Poll getVm and retry after the current operation finishes. |
Orphaned | VM run cannot be managed | The service cannot verify or manage the VM run, and the guest may still be running. | For an unverifiable run, check the process and then use forceAdopt or forceMarkDead. For a blocked VM, resolve the condition named by the message and restart hoody-vm. |
Pause a VM
Section titled “Pause a VM”POST /api/v1/vm/vms/{name}/pause
Pauses a VM. Poll getVm until state is Paused.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | Yes | The VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters. |
This endpoint does not accept a request body.
Request
Section titled “Request”curl --request POST \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/pause'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const res = await client.vm.vms.pause('dev-vm');const state = res.data.state;Responses
Section titled “Responses”Media type: application/json
The pause was accepted. Poll getVm until state is Paused.
{ "name": "dev-vm", "vm_id": "0000019a3f5c2e11", "state": "Paused", "seq": 43}Media type: application/json
The request name or specification is invalid.
{ "error": { "code": "NameInvalid", "message": "VM names must contain only lowercase letters, digits, and hyphens.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NameInvalid | Invalid VM name | The requested name does not match the required format. | Use a name containing only lowercase letters, digits, and -, starting with a letter or digit and no longer than 63 characters. |
SpecInvalid | Invalid request specification | The request contains query parameters even though this operation accepts none. | Remove all query parameters and retry. |
Media type: application/json
No VM has the requested name.
{ "error": { "code": "NotFound", "message": "No VM named dev-vm exists.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NotFound | VM not found | No VM has the requested name. | Verify the VM name and retry. |
Media type: application/json
The VM cannot accept the pause command in its current state.
{ "error": { "code": "BadState", "message": "The VM is not running or its control monitor is unresponsive.", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BadState | Invalid VM state | The VM is not running, a stop is in progress, or QEMU has stopped responding to control commands. An unresponsive monitor appears as monitor_stalled: true on getVm while the VM still reads Running. | Retry only while the VM is running and responsive. If monitor_stalled is true, stop the VM instead; the stop completes without the monitor. |
OperationInProgress | Another operation is running | Another operation on the VM has not finished. | Poll getVm and retry after the current operation finishes. |
Orphaned | VM run cannot be managed | The service cannot verify or manage the VM run, and the guest may still be running. | For an unverifiable run, check the process and then use forceAdopt or forceMarkDead. For a blocked VM, resolve the condition named by the message and restart hoody-vm. |
Resume a VM
Section titled “Resume a VM”POST /api/v1/vm/vms/{name}/resume
Resumes a paused VM. Poll getVm until state is Running.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | Yes | The VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters. |
This endpoint does not accept a request body.
Request
Section titled “Request”curl --request POST \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/resume'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const res = await client.vm.vms.resume('dev-vm');const state = res.data.state;Responses
Section titled “Responses”Media type: application/json
The resume was accepted. Poll getVm until state is Running.
{ "name": "dev-vm", "vm_id": "0000019a3f5c2e11", "state": "Running", "seq": 44}Media type: application/json
The request name or specification is invalid.
{ "error": { "code": "NameInvalid", "message": "VM names must contain only lowercase letters, digits, and hyphens.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NameInvalid | Invalid VM name | The requested name does not match the required format. | Use a name containing only lowercase letters, digits, and -, starting with a letter or digit and no longer than 63 characters. |
SpecInvalid | Invalid request specification | The request contains query parameters even though this operation accepts none. | Remove all query parameters and retry. |
Media type: application/json
No VM has the requested name.
{ "error": { "code": "NotFound", "message": "No VM named dev-vm exists.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NotFound | VM not found | No VM has the requested name. | Verify the VM name and retry. |
Media type: application/json
The VM cannot accept the resume command in its current state.
{ "error": { "code": "BadState", "message": "The VM is neither paused nor running, or its control monitor is unresponsive.", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BadState | Invalid VM state | The VM is neither paused nor running, a stop is in progress, or QEMU has stopped responding to control commands. An unresponsive monitor appears as monitor_stalled: true on getVm while the VM still reads Running. | Retry only while the VM is paused or running and responsive. If monitor_stalled is true, stop the VM instead; the stop completes without the monitor. |
OperationInProgress | Another operation is running | Another operation on the VM has not finished. | Poll getVm and retry after the current operation finishes. |
Orphaned | VM run cannot be managed | The service cannot verify or manage the VM run, and the guest may still be running. | For an unverifiable run, check the process and then use forceAdopt or forceMarkDead. For a blocked VM, resolve the condition named by the message and restart hoody-vm. |
Reset a running VM
Section titled “Reset a running VM”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | Yes | The VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters. |
This endpoint does not accept a request body.
Request
Section titled “Request”curl --request POST \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/reset'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const res = await client.vm.vms.reset('dev-vm');const state = res.data.state;Responses
Section titled “Responses”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}Media type: application/json
The request name or specification is invalid.
{ "error": { "code": "NameInvalid", "message": "VM names must contain only lowercase letters, digits, and hyphens.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NameInvalid | Invalid VM name | The requested name does not match the required format. | Use a name containing only lowercase letters, digits, and -, starting with a letter or digit and no longer than 63 characters. |
SpecInvalid | Invalid request specification | The request contains query parameters even though this operation accepts none. | Remove all query parameters and retry. |
Media type: application/json
No VM has the requested name.
{ "error": { "code": "NotFound", "message": "No VM named dev-vm exists.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NotFound | VM not found | No VM has the requested name. | Verify the VM name and retry. |
Media type: application/json
The VM cannot accept the reset command in its current state.
{ "error": { "code": "BadState", "message": "The VM is not in a state that supports this operation.", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BadState | Invalid VM state | The VM is not running (it is stopped, starting, paused, or stopping), its monitor is not answering, QEMU refused the command, or the service is shutting down. Nothing was done. | Read the current VM state and retry only when the VM is running. Resume a paused VM first. |
OperationInProgress | Another operation is running | Another operation on this VM has not finished. | Poll getVm and retry after the current operation finishes. |
Orphaned | VM run cannot be managed | The service cannot verify or manage the VM run, and the guest may still be running. | For an unverifiable run, check the process and then use forceAdopt or forceMarkDead. For a blocked VM, resolve the condition named by the message and restart hoody-vm. |
Media type: application/json
The reset command was sent, but the service could not confirm that QEMU carried it out.
{ "error": { "code": "MonitorCommandIndeterminate", "message": "The monitor did not answer in time, so the reset may or may not have been carried out.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MonitorCommandIndeterminate | Monitor command result unknown | The command was sent and QEMU did not answer in time, or the monitor closed first. The reset may or may not have been carried out. | Check the guest before sending the reset again, so the guest is not reset twice. |
Press keys in a running VM
Section titled “Press keys in a running VM”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | Yes | The VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
keys | array | Yes | The keys to press together, in order, using QEMU’s key names. Between 1 and 8 keys, each one different. |
hold_ms | integer | No | How long the keys are held down, in milliseconds, from 10 through 1000. Omitted means QEMU’s default of 100 ms. |
Accepted key names:
| Group | Names |
|---|---|
| Letters | a through z |
| Digits | 0 through 9 |
| Function keys | f1 through f12 |
| Modifiers | shift, shift_r, ctrl, ctrl_r, alt, alt_r, meta_l, meta_r |
| Editing and navigation | esc, tab, ret, spc, backspace, delete, insert, home, end, pgup, pgdn, up, down, left, right |
| Lock and system keys | caps_lock, num_lock, scroll_lock, sysrq, pause, menu |
| Punctuation | minus, equal, bracket_left, bracket_right, semicolon, apostrophe, grave_accent, backslash, comma, dot, slash, less |
| Keypad | kp_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.
Request
Section titled “Request”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'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const res = await client.vm.vms.pressKeys('dev-vm', { keys: ['ctrl', 'alt', 'delete'] });const state = res.data.state;Responses
Section titled “Responses”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}Media type: application/json
The request name or body is invalid.
{ "error": { "code": "SpecInvalid", "message": "keys must contain between 1 and 8 different accepted key names.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NameInvalid | Invalid VM name | The requested name does not match the required format. | Use a name containing only lowercase letters, digits, and -, starting with a letter or digit and no longer than 63 characters. |
SpecInvalid | Invalid request specification | The body is not valid JSON, carries an unknown field, names a key that is not accepted, names the same key twice, has no keys or more than 8, or sets hold_ms outside 10 through 1000, or the request carries query parameters, which this operation does not accept. | Send a body with keys holding between 1 and 8 different accepted key names, and hold_ms between 10 and 1000. Remove unknown fields and all query parameters. |
Media type: application/json
No VM has the requested name.
{ "error": { "code": "NotFound", "message": "No VM named dev-vm exists.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NotFound | VM not found | No VM has the requested name. | Verify the VM name and retry. |
Media type: application/json
The request body stopped arriving before the service could read it.
{ "error": { "code": "RequestBodyStalled", "message": "The request body stopped arriving.", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RequestBodyStalled | Request body stalled | The request body stopped arriving before the service could read it, so no keys were pressed. | Send the request again with the complete body. |
Media type: application/json
The VM cannot accept the key press in its current state. Nothing was done.
{ "error": { "code": "BadState", "message": "The VM is not in a state that supports this operation.", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BadState | Invalid VM state | The VM is not running (it is stopped, starting, paused, or stopping), its monitor is not answering, QEMU refused the command, or the service is shutting down. Nothing was done. | Read the current VM state and retry only when the VM is running. Resume a paused VM first. |
OperationInProgress | Another operation is running | Another operation on this VM has not finished. | Poll getVm and retry after the current operation finishes. |
Orphaned | VM run cannot be managed | The service cannot verify or manage the VM run, and the guest may still be running. | For an unverifiable run, check the process and then use forceAdopt or forceMarkDead. For a blocked VM, resolve the condition named by the message and restart hoody-vm. |
Media type: application/json
The key press was sent, but the service could not confirm that QEMU carried it out.
{ "error": { "code": "MonitorCommandIndeterminate", "message": "The monitor did not answer in time, so the keys may or may not have been pressed.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MonitorCommandIndeterminate | Monitor command result unknown | The command was sent and QEMU did not answer in time, or the monitor closed first. The key press may or may not have been carried out. | Check the guest before sending the keys again, so the combination is not pressed twice. |