# VM: Lifecycle **Page:** api/vm/lifecycle [Download Raw Markdown](./api/vm/lifecycle.md) --- # 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. Access to a computer's VM service is controlled by that computer's proxy permission rules. ## Shared response fields Every `200` response below uses the VM detail shape. ### 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 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 `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`. ### 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 `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. ## 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. A later launch failure can appear with `state: Failed`, the same nested `error` when one is available, and a prose `reason`. A `Failed` VM with no `error` carries only `reason`. This includes `RunAbnormalExit`, where the guest reached `Running` and later died. Do not expect `error.error.code` in that case. ### 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 ```bash curl --request POST \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/start' ``` ```ts 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 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. ```json { "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. ```json { "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. ```json { "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. ```json { "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. ```json { "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 `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. The graceful sequence first sends an ACPI powerdown. After the grace period (30 seconds unless `grace_seconds` or the VM's `stop_grace_seconds` sets another), it escalates to QEMU quit, `SIGTERM`, and `SIGKILL`. Unsaved guest data can be lost. ### 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 | 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 ```bash 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' ``` ```ts 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 Media type: application/json The stop was accepted. Poll getVm until `state` is `Stopped`. ```json { "name": "dev-vm", "vm_id": "0000019a3f5c2e11", "state": "Stopping", "seq": 42 } ``` Media type: application/json The request name or specification is invalid. ```json { "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. ```json { "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. ```json { "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. ```json { "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 `POST /api/v1/vm/vms/{name}/force-stop` Force-stops a VM. Poll getVm until `state` is `Stopped`. Force-stop is destructive. Unsaved guest data can be lost. ### 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 ```bash curl --request POST \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/force-stop' ``` ```ts 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 Media type: application/json The force-stop was accepted. Poll getVm until `state` is `Stopped`. ```json { "name": "dev-vm", "vm_id": "0000019a3f5c2e11", "state": "Stopping", "seq": 45 } ``` Media type: application/json The request name or specification is invalid. ```json { "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. ```json { "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. ```json { "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 `POST /api/v1/vm/vms/{name}/pause` Pauses a VM. Poll getVm until `state` is `Paused`. Pausing frees no host resources. ### 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 ```bash curl --request POST \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/pause' ``` ```ts 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 Media type: application/json The pause was accepted. Poll getVm until `state` is `Paused`. ```json { "name": "dev-vm", "vm_id": "0000019a3f5c2e11", "state": "Paused", "seq": 43 } ``` Media type: application/json The request name or specification is invalid. ```json { "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. ```json { "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. ```json { "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 `POST /api/v1/vm/vms/{name}/resume` Resumes a paused VM. Poll getVm until `state` is `Running`. ### 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 ```bash curl --request POST \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/resume' ``` ```ts 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 Media type: application/json The resume was accepted. Poll getVm until `state` is `Running`. ```json { "name": "dev-vm", "vm_id": "0000019a3f5c2e11", "state": "Running", "seq": 44 } ``` Media type: application/json The request name or specification is invalid. ```json { "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. ```json { "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. ```json { "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 `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. A reset does not shut the guest down. Anything the guest has not written to disk is lost. ### 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 ```bash curl --request POST \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/reset' ``` ```ts 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 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. ```json { "name": "dev-vm", "vm_id": "0000019a3f5c2e11", "state": "Running", "seq": 47 } ``` Media type: application/json The request name or specification is invalid. ```json { "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. ```json { "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. ```json { "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. ```json { "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 `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 | 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 | 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 ```bash 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' ``` ```ts 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 Media type: application/json QEMU pressed the keys. The VM stays in its current state. ```json { "name": "dev-vm", "vm_id": "0000019a3f5c2e11", "state": "Running", "seq": 46 } ``` Media type: application/json The request name or body is invalid. ```json { "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. ```json { "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. ```json { "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. ```json { "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. ```json { "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. |