# VM: VMs **Page:** api/vm/vms [Download Raw Markdown](./api/vm/vms.md) --- # VM: VMs 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. Kit calls are reached through the computer's URL. Who may call these routes is set by the computer's proxy permission rules. Do not send a Hoody account token to this host. ## List VMs `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. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `state` | query | `string` | No | Comma-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`. | | `phase` | query | `string` | No | Comma-separated storage phases to keep: `committed` or `creating`. An unrecognised value is refused with 400 `SpecInvalid`. | ### Responses Media type: application/json Returns every known VM, including creates still in progress. **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `[]` | `array` | Yes | Array of VM summaries. | | `[].name` | `string` | Yes | VM name. | | `[].vm_id` | `string` | No | VM identifier. | | `[].phase` | `string` | Yes | Storage phase, either `committed` or `creating`. | | `[].state` | `string` | No | Lifecycle state. A VM without a state counts as `Creating`. | | `[].share` | `object` | No | Disk usage for the VM's `share/` folder. It is absent until a measurement has completed, which does not mean the folder is empty. | | `[].share.bytes` | `integer` | Yes, when `share` is present | Allocated 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.partial` | `boolean` | Yes, when `share` is present | Whether the measurement stopped early. When `true`, `bytes` is a lower bound rather than a total. | | `[].share.sampled_unix` | `integer` | Yes, when `share` is present | Time of the measurement in Unix seconds. | | `[].share.quota_bytes` | `integer` | No | Current share quota in bytes. It is absent when the share has no limit. | | `[].share.over_quota` | `boolean` | Yes, when `share` is present | 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. 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. | ```json [ { "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 } } ] ``` Media type: application/json The request contains an unrecognised filter value. **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `error` | `object` | Yes | Error envelope. | | `error.code` | `string` | Yes | Error code. Branch on this value rather than `message`. | | `error.message` | `string` | Yes | Human-readable explanation. | | `error.retryable` | `boolean` | Yes | Whether repeating the identical request could succeed without any other change. | ```json { "error": { "code": "SpecInvalid", "message": "The state filter contains an unsupported lifecycle state.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `SpecInvalid` | Invalid list filter | The request contains an unrecognised `state` or `phase` value. | Use only the lifecycle states and storage phases documented by the `state` and `phase` parameters. | Media type: application/json The storage operation failed. **Response fields** ```json { "error": { "code": "StorageFailed", "message": "The storage operation failed.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `StorageFailed` | Storage operation failed | The service could not complete the storage operation. The error response has `retryable` set to `false`. | Resolve the storage condition before retrying the identical request. | ### Usage ```bash curl --request GET \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms?state=Running&phase=committed' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' }); const vms = await client.vm.vms.list({ state: 'Running', phase: 'committed' }); console.log(vms.data); ``` ## Get a VM `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. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `name` | path | `string` | Yes | VM name. It must contain lowercase letters, digits, and `-`, begin with a letter or digit, and be at most 63 characters long. | ### Responses Media type: application/json Returns the VM's current state, its configuration, and, while it is being created, create progress. **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `name` | `string` | Yes | VM name. | | `vm_id` | `string` | No | VM identifier. | | `state` | `string` | Yes | Lifecycle state: `Creating`, `Stopped`, `Starting`, `Running`, `Paused`, `Stopping`, `Failed`, or `Orphaned`. | | `reason` | `string` | No | Prose reason for the current state. | | `run` | `string` | No | Identifier of the current run. | | `progress` | `object` | No | Create progress. | | `progress.phase` | `string` | Yes, when `progress` is present | Create phase: `reserving`, `importing`, `committing`, `committed`, or `failed`. | | `progress.bytes_done` | `integer` | Yes, when `progress` is present | Bytes processed so far. | | `progress.bytes_total` | `integer` | Yes, when `progress` is present | Total bytes to process. | | `progress.fell_back` | `string` | No | Set when reflink cloning was unavailable and the disk was fully copied instead. | | `progress.warnings` | `array` of `string` | No | Warnings about a create that succeeded, such as an identity or TPM difference introduced by cloning. | | `progress.error` | `object` | No | Present when `progress.phase` is `failed`. It contains the background create failure. | | `progress.error.error` | `object` | Yes, when `progress.error` is present | Nested error envelope. | | `progress.error.error.code` | `string` | Yes, when `progress.error` is present | Error code. | | `progress.error.error.message` | `string` | Yes, when `progress.error` is present | Human-readable explanation. | | `progress.error.error.retryable` | `boolean` | Yes, when `progress.error` is present | Whether repeating the identical request could succeed without any other change. | | `sidecars` | `array` | No | Health of the VM's helper processes. It is 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 | Committed 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_mib` | `integer` | Yes, when `spec` is present | Guest RAM in MiB. | | `spec.vcpus` | `integer` | Yes, when `spec` is present | Number of virtual CPUs. | | `spec.disk_bytes` | `integer` | No | System disk size in bytes. It is absent when the size cannot be read. | | `spec.firmware` | `string` | Yes, when `spec` is present | Firmware: `uefi`, `uefi-secure-boot`, or `bios`. | | `spec.bus` | `string` | Yes, when `spec` is present | System disk controller: `virtio` or `sata`. | | `spec.display_adapter` | `string` | Yes, when `spec` is present | Guest display adapter: `vga` or `virtio-vga`. It is fixed when the VM is created, and new VMs use `virtio-vga`. | | `spec.cpu` | `string` | Yes, when `spec` is present | CPU model: `qemu-default`, `westmere`, or `host`. The `portable` creation setting produces `westmere`. | | `spec.tpm` | `boolean` | Yes, when `spec` is present | Whether the VM has a TPM 2.0. | | `spec.file_sharing` | `boolean` | Yes, when `spec` is present | Whether the `share/` folder is shared into the guest. | | `spec.agent` | `boolean` | Yes, when `spec` is present | Whether the guest-agent channel is configured. | | `spec.console` | `boolean` | Yes, when `spec` is present | Whether the serial console is configured. | | `spec.console_input` | `boolean` | Yes, when `spec` is present | Whether console input is allowed. | | `spec.audio` | `string` | Yes, when `spec` is present | Audio device: `none` or `output`. | | `spec.machine_type` | `string` | Yes, when `spec` is present | QEMU machine type to which the VM is pinned. | | `spec.display` | `integer` | No | X display number. It is absent when the VM is headless. | | `spec.cdroms` | `array` of `string` or `null` | No | Attached read-only media in boot order. A `null` value is an empty slot. | | `spec.autostart` | `boolean` | Yes, when `spec` is present | Whether the VM starts automatically with the service. | | `spec.disk_bps` | `integer` | No | Disk throughput limit in bytes per second. It is absent when unlimited. | | `spec.disk_iops` | `integer` | No | Disk operations-per-second limit. It is absent when unlimited. | | `spec.share_quota_bytes` | `integer` | No | Share quota in bytes. It is absent when unlimited and is checked only when the VM starts. | | `spec.ports` | `array` | No | Inbound port forwards. It is absent when the VM accepts no inbound connections. | | `spec.ports[].proto` | `string` | No | Transport protocol: `tcp` or `udp`. Default: `"tcp"`. | | `spec.ports[].host` | `integer` | Yes | Port opened on the computer's addresses. It is shared by every VM in the computer. | | `spec.ports[].guest` | `integer` | Yes | Port on which the guest listens. | | `spec.stop_grace_seconds` | `integer` | No | How long a graceful stop waits before forcing the VM off, in seconds. It is absent when the default of 30 applies. | | `display_url` | `string` | No | Browser 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_stalled` | `boolean` | No | Whether the QMP monitor has stopped answering. It is omitted when `false`. | | `seq` | `integer` | No | VM event counter as of this response. It is absent when no events have been published for the VM. | | `error` | `object` | No | Typed reason the current run failed. The code is nested at `error.error.code`. | | `error.error` | `object` | Yes, when `error` is present | Nested error envelope. | | `error.error.code` | `string` | Yes, when `error` is present | Error code. | | `error.error.message` | `string` | Yes, when `error` is present | Human-readable explanation. | | `error.error.retryable` | `boolean` | Yes, when `error` is present | Whether repeating the identical request could succeed without any other change. | | `share` | `object` | No | Disk usage for the VM's `share/` folder. It is absent until a measurement has completed. | | `share.bytes` | `integer` | Yes, when `share` is present | Allocated 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.partial` | `boolean` | Yes, when `share` is present | Whether the measurement stopped early. When `true`, `bytes` is a lower bound. | | `share.sampled_unix` | `integer` | Yes, when `share` is present | Time of the measurement in Unix seconds. | | `share.quota_bytes` | `integer` | No | Current share quota in bytes. | | `share.over_quota` | `boolean` | Yes, when `share` is present | 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 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`. ```json { "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 } } ``` Media type: application/json The VM name is invalid, or the request contains query parameters that this operation does not accept. **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `error` | `object` | Yes | Error envelope. | | `error.code` | `string` | Yes | Error code. | | `error.message` | `string` | Yes | Human-readable explanation. | | `error.retryable` | `boolean` | Yes | Whether repeating the identical request could succeed without any other change. | ```json { "error": { "code": "NameInvalid", "message": "The VM name does not match the required format.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `NameInvalid` | Invalid VM name | The name in the path does not match the required VM name format. | Use lowercase letters, digits, and `-`, begin with a letter or digit, and limit the name to 63 characters. | | `SpecInvalid` | Invalid request specification | The request contains query parameters, but this operation accepts none. | Remove all query parameters from the request. | Media type: application/json No VM has the requested name. **Response fields** ```json { "error": { "code": "NotFound", "message": "No VM has this name.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `NotFound` | VM not found | No VM has the requested name. | Confirm the VM name with the List VMs operation. | Media type: application/json The VM is not ready to be managed, another operation is active, or the service cannot verify the VM's run. **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `error` | `object` | Yes | Error envelope. | | `error.code` | `string` | Yes | Error code. | | `error.message` | `string` | Yes | Human-readable explanation. | | `error.retryable` | `boolean` | Yes | Whether repeating the identical request could succeed without any other change. | ```json { "error": { "code": "OperationInProgress", "message": "The VM was recently created and is not ready to be managed yet.", "retryable": true } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `OperationInProgress` | Operation in progress | The VM has just been created and is not ready to be managed yet. | Retry shortly. | | `BadState` | VM state changed during the request | A create for this name failed while the VM was being read. | Read the VM again. | | `Orphaned` | VM run cannot be managed | The service cannot verify the VM's run, or it has blocked the VM after finding multiple possible live runs or an indeterminate delete. The guest may still be running. The error message distinguishes the condition. | For an unverifiable run, check the process, then use `forceAdopt` or `forceMarkDead`; `forceMarkDead` is accepted only when the disk is not locked. For a blocked VM, both actions are refused. Resolve the condition named in the message and restart `hoody-vm`. | Media type: application/json The storage operation failed. **Response fields** ```json { "error": { "code": "StorageFailed", "message": "The storage operation failed.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `StorageFailed` | Storage operation failed | The service could not complete the storage operation. The error response has `retryable` set to `false`. | Resolve the storage condition before retrying the identical request. | ### Usage ```bash curl --request GET \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' }); const vm = await client.vm.vms.get('dev-vm'); console.log(vm.data.state); ``` ## Open a VM's display `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. ### 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. | | `format` | query | `string` | No | `json` answers 200 with `{name, display, url}` instead of redirecting. Absent: redirect. Any other value is refused with 400 `SpecInvalid`. | ### Responses 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** | Field | Type | Required | Description | |---|---|---|---| | `name` | `string` | Yes | VM name. | | `display` | `integer` | Yes | The VM's X display number, as in `spec.display`. | | `url` | `string` | No | Browser 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. | ```json { "name": "dev-vm", "display": 7, "url": "https://{projectId}-{computerId}-display-7.{server}.computers.hoody.com" } ``` Media type: not recorded Redirects to the VM's display. The address is in the `Location` response header, as a URI. Media type: application/json `format` has a value other than `json`, or the query has another key. For the redirect, there is no address to redirect to: the request did not arrive through the computer's `vm` URL, or the VM's display is `0`. **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `error` | `object` | Yes | Error envelope. | | `error.code` | `string` | Yes | Error code. Branch on this value rather than `message`. | | `error.message` | `string` | Yes | Human-readable explanation. | | `error.retryable` | `boolean` | Yes | Whether repeating the identical request could succeed without any other change. | ```json { "error": { "code": "SpecInvalid", "message": "The format query parameter must be json.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `SpecInvalid` | Invalid display request | `format` has a value other than `json`, the query carries another key, or there is no address to redirect to because the request did not arrive through the computer's `vm` URL or the VM's display is `0`. | Send only `format=json`, or call the route through the computer's `vm` URL for a VM whose display is not `0`. | Media type: application/json No VM has the requested name. **Response fields** ```json { "error": { "code": "NotFound", "message": "No VM has this name.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `NotFound` | VM not found | No VM has the requested name. | Confirm the VM name with the List VMs operation. | Media type: application/json The VM has no display, is not ready to be managed, its create failed, or the service cannot manage it. **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `error` | `object` | Yes | Error envelope. | | `error.code` | `string` | Yes | Error code. | | `error.message` | `string` | Yes | Human-readable explanation. | | `error.retryable` | `boolean` | Yes | Whether repeating the identical request could succeed without any other change. | ```json { "error": { "code": "DisplayNotConfigured", "message": "The VM is headless and has no display to open.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `DisplayNotConfigured` | VM has no display | The VM is headless, so it has no display address. | Give the VM a display with the Reconfigure a stopped VM operation while it is stopped. | | `OperationInProgress` | Operation in progress | The VM is still being created, or has just been created and is not ready to be managed yet. | Retry shortly. | | `BadState` | VM create failed | The VM's create failed. | Delete the VM and create it again. | | `Orphaned` | VM run cannot be managed | The service cannot verify the VM's run, or it has blocked the VM after finding multiple possible live runs or an indeterminate delete. The guest may still be running. The error message distinguishes the condition. | For an unverifiable run, check the process, then use `forceAdopt` or `forceMarkDead`; `forceMarkDead` is accepted only when the disk is not locked. For a blocked VM, both actions are refused. Resolve the condition named in the message and restart `hoody-vm`. | Media type: application/json The storage operation failed. **Response fields** ```json { "error": { "code": "StorageFailed", "message": "The storage operation failed.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `StorageFailed` | Storage operation failed | The service could not complete the storage operation. The error response has `retryable` set to `false`. | Resolve the storage condition before retrying the identical request. | ### Usage ```bash 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. ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' }); const display = await client.vm.vms.getDisplay('dev-vm'); console.log(display.data); ``` ## Create a VM `POST /api/v1/vm/vms` Creates a VM from a template, blank disk, ISO, offline disk image, existing VM disk, or snapshot artifact. Creation is asynchronous. The operation returns 202 and continues in the background. Poll the VM with the Get a VM operation until `progress.phase` is `committed` or `failed`. A background failure appears in `progress.error`, not in the create operation's status. ### Request body #### VM fields | Name | Type | Required | Description | |---|---|---|---| | `name` | `string` | Yes | VM name. It must match `^[a-z0-9][a-z0-9-]{0,62}$`. | | `source` | `object` | Yes | Tagged disk source. Its `type` must be one of the six values in the source union below. | | `memory_mib` | `integer` | Yes | Guest RAM in MiB. Minimum: `1`. It is required even for a `snapshot-artifact` source because an artifact does not record sizing. | | `vcpus` | `integer` | Yes | Number of virtual CPUs. Minimum: `1`, maximum: `4096`. It is required even for a `snapshot-artifact` source. | | `firmware` | `string` | No | Firmware: `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. | | `bus` | `string` | No | System 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. | | `display` | `integer` or `string` | No | X 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_id` | `integer` or `string` | No | Another name for `display`, with the same values and meaning, including `"auto"`. Send either field. If both are sent, they must have the same value. | | `cpu` | `string` | No | CPU 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. | | `agent` | `boolean` | No | Whether to configure the guest-agent channel. Default: `true`. It is fixed at creation. A `snapshot-artifact` source determines this setting. | | `console` | `boolean` | No | Whether to configure a serial console. Default: `true`. It is fixed at creation. A `snapshot-artifact` source determines this setting. | | `console_input` | `boolean` | No | Whether 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. | | `audio` | `string` | No | Audio 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. | | `share` | `boolean` | No | Whether 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. | | `os` | `string` | No | Guest 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_boot` | `boolean` | No | Whether 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_bps` | `integer` | No | Disk 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_iops` | `integer` | No | Disk 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_bytes` | `integer` | No | Size 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. | | `ports` | `array` | No | Inbound port forwards. The array can contain at most 128 entries. Omitting it or passing an empty array makes the VM outbound-only. | | `autostart` | `boolean` | No | Whether the VM starts automatically when the service starts. Default: `false`. | | `tpm` | `boolean` | No | Whether 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_seconds` | `integer` | No | How 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. | #### Source union The `source` object is a tagged union on `type`. Each variant requires its own fields and rejects fields belonging to other variants. | `type` | Required fields | Description | |---|---|---| | `template` | `type`, `id` | Creates the VM from a template catalog entry. Templates include the guest drivers required by the selected operating system. | | `blank` | `type`, `gib` | Creates a VM with an empty, sparsely allocated disk of the requested size in GiB. | | `iso` | `type`, `gib`, and exactly one of `sha256` or `path` | Installs 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-file` | `type`, `path` | Copies an existing host disk image into the VM. The source can be removed after the copy completes. | | `vm-disk` | `type`, `name` | Clones the disk of an existing VM. The source VM must not be running. The clone receives a new identity and a new TPM. | | `snapshot-artifact` | `type`, `sha256`, plus the top-level `bus` | Rebuilds 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 field | Applies to | Type | Required | Description | |---|---|---|---|---| | `source.id` | `template` | `string` | Yes | Template catalog identifier. | | `source.gib` | `blank`, `iso` | `integer` | Yes | Disk 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.sha256` | `iso` | `string` | Conditionally | SHA-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.sha256` | `snapshot-artifact` | `string` | Yes | SHA-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.path` | `iso` | `string` | Conditionally | Absolute 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.path` | `offline-file` | `string` | Yes | Absolute path to a disk image already on the host. The image is copied into the VM, and its contents are not verified. | | `source.url` | `iso` | `string` | No | A URL is not accepted. Download the image into the ISO store first, then create the VM from its `sha256`. | | `source.name` | `vm-disk` | `string` | Yes | Name of the existing VM whose disk is cloned. The source must not be running. | | `source.duplicate_tpm_identity` | `snapshot-artifact` | `boolean` | Conditionally | Default: `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. #### Port forward fields | Name | Type | Required | Description | |---|---|---|---| | `proto` | `string` | No | Transport protocol: `tcp` or `udp`. Default: `"tcp"`. TCP and UDP forwards are separate. | | `host` | `integer` | Yes | Port 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. | | `guest` | `integer` | Yes | Port on which the guest listens, from `1` to `65535`. It is not shared between VMs. | #### Example body ```json { "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 } ``` ### Responses 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** | Field | Type | Required | Description | |---|---|---|---| | `name` | `string` | Yes | Name of the VM being created. | | `vm_id` | `string` | Yes | Identifier assigned to the VM. | | `state` | `string` | Yes | Initial VM state. | | `display` | `integer` | No | X 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. ```json { "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 Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `NotFound` | Source VM not found | The `vm-disk` source VM does not exist. | Check the source VM name. | | `SourceBusy` | Source is busy or changed | The 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. | | `InsufficientSpace` | Insufficient storage space | The 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`. Media type: application/json The body is malformed or contains an invalid field value, or the request contains unsupported query parameters. **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `error` | `object` | Yes | Error envelope. | | `error.code` | `string` | Yes | Error code. | | `error.message` | `string` | Yes | Human-readable explanation, including the invalid field and rule when applicable. | | `error.retryable` | `boolean` | Yes | Whether repeating the identical request could succeed without any other change. | ```json { "error": { "code": "SpecInvalid", "message": "The vcpus field exceeds the maximum supported value.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `SpecInvalid` | Invalid create request | The body is malformed, a field violates its schema, the name does not match `^[a-z0-9][a-z0-9-]{0,62}$`, or the request contains query parameters. | Correct the field named by the message and remove unsupported query parameters. This operation does not return `NameInvalid` because the name is supplied in the body. | Media type: application/json The request body stopped arriving. **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `error` | `object` | Yes | Error envelope. | | `error.code` | `string` | Yes | Error code. | | `error.message` | `string` | Yes | Human-readable explanation. | | `error.retryable` | `boolean` | Yes | Whether repeating the identical request could succeed without any other change. | ```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 it was complete. | Retry the request with `error.retryable` set to `true`. | Media type: application/json The name is already in use, another operation owns it, a requested host port conflicts, the display number cannot be used, or the source VM is orphaned. **Response fields** ```json { "error": { "code": "AlreadyExists", "message": "A VM with this name already exists.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `AlreadyExists` | VM already exists | A VM with the requested name already exists. | Choose a different name or inspect the existing VM. | | `OperationInProgress` | Operation in progress | Another operation holds the requested name. | Retry later. | | `PortForwardConflict` | Port forward conflict | A host port in `ports` is already declared by another VM, whether that VM is running or stopped. | Choose an unused host port or remove the conflicting rule. | | `DisplayRangeExhausted` | Display range exhausted | `display` is `"auto"` and no number in the automatic range is free. | Choose an explicit display number, or free one in the automatic range. | | `DisplayInUse` | Display number already in use | `display` is a number that something else is already using. | Choose another number, or use `"auto"`. | | `Orphaned` | Source VM cannot be managed | The `vm-disk` source VM is orphaned, so its disk cannot be read. The source guest may still be running. | Resolve the orphaned source condition before creating the new VM. | Media type: application/json A storage error occurred on the host. **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `error` | `object` | Yes | Error envelope. | | `error.code` | `string` | Yes | Error code. | | `error.message` | `string` | Yes | Human-readable explanation. | | `error.retryable` | `boolean` | Yes | Whether repeating the identical request could succeed without any other change. | ```json { "error": { "code": "StorageFailed", "message": "A storage error occurred on the host.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `StorageFailed` | Storage operation failed | The service could not complete the storage operation. The error response has `retryable` set to `false`. | Resolve the storage condition before retrying the identical request. | Media type: application/json The service could not check whether the display number is in use. With `"auto"` no number was picked, and with an explicit number nothing was created. **Response fields** ```json { "error": { "code": "DisplayUnavailable", "message": "The display service could not be reached to check the display number.", "retryable": true } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `DisplayUnavailable` | Display availability check failed | The service could not check whether the display number is in use. With `"auto"` no number was picked, and with an explicit number nothing was created. | Retry the create, or for `"auto"` give an explicit display number. | ### Usage ```bash 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' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' }); const created = await client.vm.vms.create({ 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 }); console.log(created.data); ``` ## Reconfigure a stopped VM `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`. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `name` | path | `string` | Yes | VM name. It must contain lowercase letters, digits, and `-`, begin with a letter or digit, and be at most 63 characters long. | ### Request body | Name | Type | Required | Description | |---|---|---|---| | `memory_mib` | `integer` | No | Guest RAM in MiB from the next start. Minimum: `1`. Host capacity is checked at the next start, not when the change is saved. | | `vcpus` | `integer` | No | Number of virtual CPUs from the next start. Minimum: `1`, maximum: `4096`. | | `disk_gib` | `integer` | No | Grow 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. | | `display` | `integer` or `string` or `null` | No | Move 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_id` | `integer` or `string` or `null` | No | Another name for `display` with the same values and meaning. Send either field. If both are sent, they must have the same value. | | `cdroms` | `array` of `string` or `null` | No | Replace 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`. | | `autostart` | `boolean` | No | Whether the VM starts automatically when the service starts. | | `disk_bps` | `integer` or `null` | No | Disk 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_iops` | `integer` or `null` | No | Disk 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_bytes` | `integer` or `null` | No | Size 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. | | `ports` | `array` | No | Replace 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_seconds` | `integer` or `null` | No | How 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. ```json { "memory_mib": 6144, "vcpus": 4, "display": null, "cdroms": [], "disk_bps": 104857600, "disk_iops": 1000, "share_quota_bytes": 10737418240, "ports": [], "stop_grace_seconds": 60 } ``` ### Responses Media type: application/json Returns the VM's configuration after the change, together with any warnings. **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `name` | `string` | Yes | VM name. | | `vm_id` | `string` | Yes | VM identifier. | | `spec` | `object` | Yes | Updated VM configuration. | | `spec.memory_mib` | `integer` | Yes | Guest RAM in MiB. | | `spec.vcpus` | `integer` | Yes | Number of virtual CPUs. | | `spec.disk_bytes` | `integer` | No | System disk size in bytes. | | `spec.firmware` | `string` | Yes | Firmware: `uefi`, `uefi-secure-boot`, or `bios`. | | `spec.bus` | `string` | Yes | System disk controller: `virtio` or `sata`. | | `spec.display_adapter` | `string` | Yes | Guest display adapter: `vga` or `virtio-vga`. It is fixed when the VM is created. | | `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 `share/` folder is shared into the guest. | | `spec.agent` | `boolean` | Yes | Whether the guest-agent channel is configured. | | `spec.console` | `boolean` | Yes | Whether the serial console is configured. | | `spec.console_input` | `boolean` | Yes | Whether console input is allowed. | | `spec.audio` | `string` | Yes | Audio device: `none` or `output`. | | `spec.machine_type` | `string` | Yes | QEMU machine type to which the VM is pinned. | | `spec.display` | `integer` | No | X display number. It is absent when the VM is headless. | | `spec.cdroms` | `array` of `string` or `null` | No | Attached read-only media in boot order. A `null` value is an empty slot. | | `spec.autostart` | `boolean` | Yes | Whether the VM starts automatically with the service. | | `spec.disk_bps` | `integer` | No | Disk throughput limit in bytes per second. It is absent when unlimited. | | `spec.disk_iops` | `integer` | No | Disk operations-per-second limit. It is absent when unlimited. | | `spec.share_quota_bytes` | `integer` | No | Share quota in bytes. It is checked only when the VM starts. | | `spec.ports` | `array` | No | Inbound port forwards. | | `spec.ports[].proto` | `string` | No | Transport protocol: `tcp` or `udp`. Default: `"tcp"`. | | `spec.ports[].host` | `integer` | Yes | Port opened on the computer's addresses. | | `spec.ports[].guest` | `integer` | Yes | Port on which the guest listens. | | `spec.stop_grace_seconds` | `integer` | No | How long a graceful stop waits before forcing the VM off, in seconds. It is absent when the default of 30 applies. | | `warnings` | `array` of `string` | No | Details about changes that succeeded, such as devices added to the guest when a display was enabled. | ```json { "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": [] } ``` Media type: application/json The name or request body is invalid. **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `error` | `object` | Yes | Error envelope. | | `error.code` | `string` | Yes | Error code. | | `error.message` | `string` | Yes | Human-readable explanation. | | `error.retryable` | `boolean` | Yes | Whether repeating the identical request could succeed without any other change. | ```json { "error": { "code": "SpecInvalid", "message": "disk_gib cannot be combined with other fields.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `NameInvalid` | Invalid VM name | The name in the path does not match the required VM name format. | Use lowercase letters, digits, and `-`, begin with a letter or digit, and limit the name to 63 characters. | | `SpecInvalid` | Invalid reconfiguration request | The body is empty, a value is invalid, `disk_gib` is combined with another field, the disk is missing, `disk_gib` is smaller than the current size, or the request contains query parameters. | Correct the named field, remove unsupported query parameters, and send `disk_gib` alone when growing the disk. | Media type: application/json No VM has the requested name. **Response fields** ```json { "error": { "code": "NotFound", "message": "No VM has this name.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `NotFound` | VM not found | No VM has the requested name. | Confirm the VM name with the List VMs operation. | Media type: application/json The request body stopped arriving. **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `error` | `object` | Yes | Error envelope. | | `error.code` | `string` | Yes | Error code. | | `error.message` | `string` | Yes | Human-readable explanation. | | `error.retryable` | `boolean` | Yes | Whether repeating the identical request could succeed without any other change. | ```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 it was complete. | Retry the request with `error.retryable` set to `true`. | Media type: application/json The VM is not stopped, another operation is active, the VM is orphaned, a host port conflicts, or the requested display number cannot be used. **Response fields** ```json { "error": { "code": "BadState", "message": "The VM must be stopped before it can be reconfigured.", "retryable": true } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `BadState` | VM is not stopped | The VM is running or otherwise not in a state that permits reconfiguration. The error response has `retryable` set to `true`. | Stop the VM before reconfiguring it. | | `OperationInProgress` | Operation in progress | Another operation on the VM is active. | Retry later. | | `Orphaned` | VM run cannot be managed | The service cannot verify the VM's run, or it has blocked the VM after finding multiple possible live runs or an indeterminate delete. The guest may still be running. The error message distinguishes the condition. | For an unverifiable run, check the process, then use `forceAdopt` or `forceMarkDead`; `forceMarkDead` is accepted only when the disk is not locked. For a blocked VM, both actions are refused. Resolve the condition named in the message and restart `hoody-vm`. | | `PortForwardConflict` | Port forward conflict | A host port in `ports` is already declared by another VM, whether that VM is running or stopped. | Choose an unused host port or remove the conflicting rule. | | `DisplayRangeExhausted` | Display range exhausted | `display` is `"auto"` and no number in the automatic range is free. | Choose an explicit display number, or free one in the automatic range. | | `DisplayInUse` | Display number already in use | `display` is a number that something other than this VM is already using. | Choose another number, or use `"auto"`. | Media type: application/json The storage operation failed. **Response fields** ```json { "error": { "code": "StorageFailed", "message": "The storage operation failed.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `StorageFailed` | Storage operation failed | The service could not complete the storage operation. The error response has `retryable` set to `false`. | Resolve the storage condition before retrying the identical request. | Media type: application/json The service could not check whether the display number is in use, so nothing was changed. With `"auto"` no number was picked. **Response fields** ```json { "error": { "code": "DisplayUnavailable", "message": "The display service could not be reached to check the display number.", "retryable": true } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `DisplayUnavailable` | Display availability check failed | The service could not check whether the display number is in use, so nothing was changed. With `"auto"` no number was picked. | Retry the request, or for `"auto"` give an explicit display number. | Media type: application/json There is not enough free space to grow the disk to the requested size. **Response fields** ```json { "error": { "code": "InsufficientSpace", "message": "There is not enough free space to grow the disk to the requested size.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `InsufficientSpace` | Insufficient storage space | The storage system does not have enough free space to grow the disk to the requested size. | Request a smaller disk size or make additional storage available before retrying. | ### Usage ```bash 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' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' }); const updated = await client.vm.vms.update('dev-vm', { memory_mib: 6144, vcpus: 4, display: null, cdroms: [], disk_bps: 104857600, disk_iops: 1000, share_quota_bytes: 10737418240, ports: [], stop_grace_seconds: 60 }); console.log(updated.data); ``` ## 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. ### 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. | | `slot` | path | `integer` | Yes | The CD-ROM slot, counted from 0 in the order of the VM's `cdroms`. Slot 0 is the one the VM boots from. | ### Request body | Name | Type | Required | Description | |---|---|---|---| | `source` | `string` | Yes | Absolute 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. | ### Responses Media type: application/json QEMU opened the disc in the slot, and `spec.cdroms` names it. **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `name` | `string` | Yes | VM name. | | `vm_id` | `string` | No | VM identifier. | | `state` | `string` | Yes | Lifecycle state: `Creating`, `Stopped`, `Starting`, `Running`, `Paused`, `Stopping`, `Failed`, or `Orphaned`. | | `reason` | `string` | No | Prose reason for the current state. | | `run` | `string` | No | Identifier of the current run. | | `progress` | `object` | No | Create progress. | | `progress.phase` | `string` | Yes, when `progress` is present | Create phase: `reserving`, `importing`, `committing`, `committed`, or `failed`. | | `progress.bytes_done` | `integer` | Yes, when `progress` is present | Bytes processed so far. | | `progress.bytes_total` | `integer` | Yes, when `progress` is present | Total bytes to process. | | `progress.fell_back` | `string` | No | Set when reflink cloning was unavailable and the disk was fully copied instead. | | `progress.warnings` | `array` of `string` | No | Warnings about a create that succeeded. | | `progress.error` | `object` | No | Present when `progress.phase` is `failed`. It contains the background create failure. | | `progress.error.error` | `object` | Yes, when `progress.error` is present | Nested error envelope. | | `progress.error.error.code` | `string` | Yes, when `progress.error` is present | Error code. | | `progress.error.error.message` | `string` | Yes, when `progress.error` is present | Human-readable explanation. | | `progress.error.error.retryable` | `boolean` | Yes, when `progress.error` is present | Whether repeating the identical request could succeed without any other change. | | `sidecars` | `array` | No | Health of the VM's helper processes. It is 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 | Committed VM configuration. It can be absent during creation or when it cannot be read. | | `spec.memory_mib` | `integer` | Yes, when `spec` is present | Guest RAM in MiB. | | `spec.vcpus` | `integer` | Yes, when `spec` is present | Number of virtual CPUs. | | `spec.disk_bytes` | `integer` | No | System disk size in bytes. | | `spec.firmware` | `string` | Yes, when `spec` is present | Firmware: `uefi`, `uefi-secure-boot`, or `bios`. | | `spec.bus` | `string` | Yes, when `spec` is present | System disk controller: `virtio` or `sata`. | | `spec.display_adapter` | `string` | Yes, when `spec` is present | Guest display adapter: `vga` or `virtio-vga`. | | `spec.cpu` | `string` | Yes, when `spec` is present | CPU model: `qemu-default`, `westmere`, or `host`. | | `spec.tpm` | `boolean` | Yes, when `spec` is present | Whether the VM has a TPM 2.0. | | `spec.file_sharing` | `boolean` | Yes, when `spec` is present | Whether the `share/` folder is shared into the guest. | | `spec.agent` | `boolean` | Yes, when `spec` is present | Whether the guest-agent channel is configured. | | `spec.console` | `boolean` | Yes, when `spec` is present | Whether the serial console is configured. | | `spec.console_input` | `boolean` | Yes, when `spec` is present | Whether console input is allowed. | | `spec.audio` | `string` | Yes, when `spec` is present | Audio device: `none` or `output`. | | `spec.machine_type` | `string` | Yes, when `spec` is present | QEMU machine type to which the VM is pinned. | | `spec.display` | `integer` | No | X display number. It is absent when the VM is headless. | | `spec.cdroms` | `array` of `string` or `null` | No | Attached read-only media in boot order. A `null` value is an empty slot. | | `spec.autostart` | `boolean` | Yes, when `spec` is present | Whether the VM starts automatically with the service. | | `spec.disk_bps` | `integer` | No | Disk throughput limit in bytes per second. It is absent when unlimited. | | `spec.disk_iops` | `integer` | No | Disk operations-per-second limit. It is absent when unlimited. | | `spec.share_quota_bytes` | `integer` | No | Share quota in bytes. It is absent when unlimited and is checked only when the VM starts. | | `spec.ports` | `array` | No | Inbound port forwards. | | `spec.ports[].proto` | `string` | No | Transport protocol: `tcp` or `udp`. Default: `"tcp"`. | | `spec.ports[].host` | `integer` | Yes | Port opened on the computer's addresses. | | `spec.ports[].guest` | `integer` | Yes | Port on which the guest listens. | | `spec.stop_grace_seconds` | `integer` | No | How long a graceful stop waits before forcing the VM off, in seconds. It is absent when the default of 30 applies. | | `display_url` | `string` | No | Browser address of the VM's display. | | `monitor_stalled` | `boolean` | No | Whether the QMP monitor has stopped answering. It is omitted when `false`. | | `seq` | `integer` | No | VM event counter as of this response. | | `error` | `object` | No | Typed reason the current run failed. The code is nested at `error.error.code`. | | `error.error` | `object` | Yes, when `error` is present | Nested error envelope. | | `error.error.code` | `string` | Yes, when `error` is present | Error code. | | `error.error.message` | `string` | Yes, when `error` is present | Human-readable explanation. | | `error.error.retryable` | `boolean` | Yes, when `error` is present | Whether repeating the identical request could succeed without any other change. | | `share` | `object` | No | Disk usage for the VM's `share/` folder. It is absent until a measurement has completed. | | `share.bytes` | `integer` | Yes, when `share` is present | Allocated size in bytes. Data shared by reflink between `share/` and the VM's disk is counted in both. | | `share.partial` | `boolean` | Yes, when `share` is present | Whether the measurement stopped early. When `true`, `bytes` is a lower bound. | | `share.sampled_unix` | `integer` | Yes, when `share` is present | Time of the measurement in Unix seconds. | | `share.quota_bytes` | `integer` | No | Current share quota in bytes. | | `share.over_quota` | `boolean` | Yes, when `share` is present | Latched state left by the last quota crossing. | ```json { "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 } } ``` Media type: application/json The VM name, slot, or request body is invalid. **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `error` | `object` | Yes | Error envelope. | | `error.code` | `string` | Yes | Error code. | | `error.message` | `string` | Yes | Human-readable explanation. | | `error.retryable` | `boolean` | Yes | Whether repeating the identical request could succeed without any other change. | ```json { "error": { "code": "SpecInvalid", "message": "The source must be an absolute path to an attachable regular file.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `NameInvalid` | Invalid VM name | The name in the path does not match the required VM name format. | Use lowercase letters, digits, and `-`, begin with a letter or digit, and limit the name to 63 characters. | | `SpecInvalid` | Invalid CD-ROM change | The body is not valid JSON, contains an unknown field, the slot is not a number or is past the VM's last slot, `source` is not an absolute path to an attachable regular file, or the request contains query parameters. | Correct the request and remove unsupported query parameters. | Media type: application/json No VM has the requested name. **Response fields** ```json { "error": { "code": "NotFound", "message": "No VM has this name.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `NotFound` | VM not found | No VM has the requested name. | Confirm the VM name with the List VMs operation. | Media type: application/json The request body stopped arriving. **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `error` | `object` | Yes | Error envelope. | | `error.code` | `string` | Yes | Error code. | | `error.message` | `string` | Yes | Human-readable explanation. | | `error.retryable` | `boolean` | Yes | Whether repeating the identical request could succeed without any other change. | ```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 it was complete. | Retry the request with `error.retryable` set to `true`. | Media type: application/json The VM or its monitor cannot accept the change, another operation is active, or the service cannot manage the VM. **Response fields** ```json { "error": { "code": "BadState", "message": "The VM must be running or paused for a CD-ROM change.", "retryable": true } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `BadState` | VM cannot accept the CD-ROM change | The VM is not running or paused, its monitor is not answering, QEMU refused the command, or the service is shutting down. The slot remains unchanged. The error response has `retryable` set to `true`. | Make sure the VM is running or paused, resolve the condition named by QEMU, and retry. If the slot was empty at start, configure it with the Reconfigure a stopped VM operation. | | `OperationInProgress` | Operation in progress | Another operation on the VM has not finished, including another CD-ROM change, or the slot changed while this call ran. | Read the VM with the Get a VM operation and retry. | | `Orphaned` | VM run cannot be managed | The service cannot verify the VM's run, or it has blocked the VM after finding multiple possible live runs or an indeterminate delete. The guest may still be running. The error message distinguishes the condition. | For an unverifiable run, check the process, then use `forceAdopt` or `forceMarkDead`; `forceMarkDead` is accepted only when the disk is not locked. For a blocked VM, both actions are refused. Resolve the condition named in the message and restart `hoody-vm`. | Media type: application/json The monitor command's result is unknown, or the VM's record could not be read or written. **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `error` | `object` | Yes | Error envelope. | | `error.code` | `string` | Yes | Error code. | | `error.message` | `string` | Yes | Human-readable explanation. | | `error.retryable` | `boolean` | Yes | Whether repeating the identical request could succeed without any other change. | ```json { "error": { "code": "MonitorCommandIndeterminate", "message": "QEMU did not answer before the monitor command deadline.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `MonitorCommandIndeterminate` | Monitor command result is unknown | The command was sent, but QEMU did not answer in time or the monitor closed first. The change may or may not have been applied. The error response has `retryable` set to `false`. | Read the VM with the Get a VM operation to inspect the recorded slot before deciding whether to retry. | | `StorageFailed` | Storage operation failed | The VM's record could not be read or written. The error response has `retryable` set to `false`. | Resolve the storage condition before retrying the identical request. | ### Usage ```bash 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' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' }); const vm = await client.vm.vms.changeCdrom('dev-vm', 0, { source: '/opt/images/dev-installer.iso' }); console.log(vm.data.state); ``` ## 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. ### 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. | | `slot` | path | `integer` | Yes | The CD-ROM slot, counted from 0 in the order of the VM's `cdroms`. Slot 0 is the one the VM boots from. | ### Responses Media type: application/json The slot is empty, and `spec.cdroms` shows `null` for it. **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `name` | `string` | Yes | VM name. | | `vm_id` | `string` | No | VM identifier. | | `state` | `string` | Yes | Lifecycle state: `Creating`, `Stopped`, `Starting`, `Running`, `Paused`, `Stopping`, `Failed`, or `Orphaned`. | | `reason` | `string` | No | Prose reason for the current state. | | `run` | `string` | No | Identifier of the current run. | | `progress` | `object` | No | Create progress. | | `progress.phase` | `string` | Yes, when `progress` is present | Create phase: `reserving`, `importing`, `committing`, `committed`, or `failed`. | | `progress.bytes_done` | `integer` | Yes, when `progress` is present | Bytes processed so far. | | `progress.bytes_total` | `integer` | Yes, when `progress` is present | Total bytes to process. | | `progress.fell_back` | `string` | No | Set when reflink cloning was unavailable and the disk was fully copied instead. | | `progress.warnings` | `array` of `string` | No | Warnings about a create that succeeded. | | `progress.error` | `object` | No | Present when `progress.phase` is `failed`. It contains the background create failure. | | `progress.error.error` | `object` | Yes, when `progress.error` is present | Nested error envelope. | | `progress.error.error.code` | `string` | Yes, when `progress.error` is present | Error code. | | `progress.error.error.message` | `string` | Yes, when `progress.error` is present | Human-readable explanation. | | `progress.error.error.retryable` | `boolean` | Yes, when `progress.error` is present | Whether repeating the identical request could succeed without any other change. | | `sidecars` | `array` | No | Health of the VM's helper processes. It is 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 | Committed VM configuration. It can be absent during creation or when it cannot be read. | | `spec.memory_mib` | `integer` | Yes, when `spec` is present | Guest RAM in MiB. | | `spec.vcpus` | `integer` | Yes, when `spec` is present | Number of virtual CPUs. | | `spec.disk_bytes` | `integer` | No | System disk size in bytes. | | `spec.firmware` | `string` | Yes, when `spec` is present | Firmware: `uefi`, `uefi-secure-boot`, or `bios`. | | `spec.bus` | `string` | Yes, when `spec` is present | System disk controller: `virtio` or `sata`. | | `spec.display_adapter` | `string` | Yes, when `spec` is present | Guest display adapter: `vga` or `virtio-vga`. | | `spec.cpu` | `string` | Yes, when `spec` is present | CPU model: `qemu-default`, `westmere`, or `host`. | | `spec.tpm` | `boolean` | Yes, when `spec` is present | Whether the VM has a TPM 2.0. | | `spec.file_sharing` | `boolean` | Yes, when `spec` is present | Whether the `share/` folder is shared into the guest. | | `spec.agent` | `boolean` | Yes, when `spec` is present | Whether the guest-agent channel is configured. | | `spec.console` | `boolean` | Yes, when `spec` is present | Whether the serial console is configured. | | `spec.console_input` | `boolean` | Yes, when `spec` is present | Whether console input is allowed. | | `spec.audio` | `string` | Yes, when `spec` is present | Audio device: `none` or `output`. | | `spec.machine_type` | `string` | Yes, when `spec` is present | QEMU machine type to which the VM is pinned. | | `spec.display` | `integer` | No | X display number. It is absent when the VM is headless. | | `spec.cdroms` | `array` of `string` or `null` | No | Attached read-only media in boot order. A `null` value is an empty slot. | | `spec.autostart` | `boolean` | Yes, when `spec` is present | Whether the VM starts automatically with the service. | | `spec.disk_bps` | `integer` | No | Disk throughput limit in bytes per second. It is absent when unlimited. | | `spec.disk_iops` | `integer` | No | Disk operations-per-second limit. It is absent when unlimited. | | `spec.share_quota_bytes` | `integer` | No | Share quota in bytes. It is absent when unlimited and is checked only when the VM starts. | | `spec.ports` | `array` | No | Inbound port forwards. | | `spec.ports[].proto` | `string` | No | Transport protocol: `tcp` or `udp`. Default: `"tcp"`. | | `spec.ports[].host` | `integer` | Yes | Port opened on the computer's addresses. | | `spec.ports[].guest` | `integer` | Yes | Port on which the guest listens. | | `spec.stop_grace_seconds` | `integer` | No | How long a graceful stop waits before forcing the VM off, in seconds. It is absent when the default of 30 applies. | | `display_url` | `string` | No | Browser address of the VM's display. | | `monitor_stalled` | `boolean` | No | Whether the QMP monitor has stopped answering. It is omitted when `false`. | | `seq` | `integer` | No | VM event counter as of this response. | | `error` | `object` | No | Typed reason the current run failed. The code is nested at `error.error.code`. | | `error.error` | `object` | Yes, when `error` is present | Nested error envelope. | | `error.error.code` | `string` | Yes, when `error` is present | Error code. | | `error.error.message` | `string` | Yes, when `error` is present | Human-readable explanation. | | `error.error.retryable` | `boolean` | Yes, when `error` is present | Whether repeating the identical request could succeed without any other change. | | `share` | `object` | No | Disk usage for the VM's `share/` folder. It is absent until a measurement has completed. | | `share.bytes` | `integer` | Yes, when `share` is present | Allocated size in bytes. Data shared by reflink between `share/` and the VM's disk is counted in both. | | `share.partial` | `boolean` | Yes, when `share` is present | Whether the measurement stopped early. When `true`, `bytes` is a lower bound. | | `share.sampled_unix` | `integer` | Yes, when `share` is present | Time of the measurement in Unix seconds. | | `share.quota_bytes` | `integer` | No | Current share quota in bytes. | | `share.over_quota` | `boolean` | Yes, when `share` is present | Latched state left by the last quota crossing. | ```json { "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 } } ``` Media type: application/json The VM name or slot is invalid. **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `error` | `object` | Yes | Error envelope. | | `error.code` | `string` | Yes | Error code. | | `error.message` | `string` | Yes | Human-readable explanation. | | `error.retryable` | `boolean` | Yes | Whether repeating the identical request could succeed without any other change. | ```json { "error": { "code": "SpecInvalid", "message": "The slot is not a number or is past the VM's last slot.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `NameInvalid` | Invalid VM name | The name in the path does not match the required VM name format. | Use lowercase letters, digits, and `-`, begin with a letter or digit, and limit the name to 63 characters. | | `SpecInvalid` | Invalid CD-ROM eject | The slot is not a number or is past the VM's last slot, or the request contains query parameters. | Send a valid slot number and remove unsupported query parameters. | Media type: application/json No VM has the requested name. **Response fields** ```json { "error": { "code": "NotFound", "message": "No VM has this name.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `NotFound` | VM not found | No VM has the requested name. | Confirm the VM name with the List VMs operation. | Media type: application/json The VM or its monitor cannot eject the disc, another operation is active, or the service cannot manage the VM. **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `error` | `object` | Yes | Error envelope. | | `error.code` | `string` | Yes | Error code. | | `error.message` | `string` | Yes | Human-readable explanation. | | `error.retryable` | `boolean` | Yes | Whether repeating the identical request could succeed without any other change. | ```json { "error": { "code": "BadState", "message": "The VM must be running or paused for a CD-ROM eject.", "retryable": true } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `BadState` | VM cannot eject the disc | The VM is not running or paused, its monitor is not answering, QEMU refused the command, or the service is shutting down. The slot remains unchanged. The error response has `retryable` set to `true`. | Make sure the VM is running or paused, ask the guest to release a locked tray, and retry. | | `OperationInProgress` | Operation in progress | Another operation on the VM has not finished, including another CD-ROM change, or the slot changed while this call ran. | Read the VM with the Get a VM operation and retry. | | `Orphaned` | VM run cannot be managed | The service cannot verify the VM's run, or it has blocked the VM after finding multiple possible live runs or an indeterminate delete. The guest may still be running. The error message distinguishes the condition. | For an unverifiable run, check the process, then use `forceAdopt` or `forceMarkDead`; `forceMarkDead` is accepted only when the disk is not locked. For a blocked VM, both actions are refused. Resolve the condition named in the message and restart `hoody-vm`. | Media type: application/json The monitor command's result is unknown, or the VM's record could not be read or written. **Response fields** ```json { "error": { "code": "MonitorCommandIndeterminate", "message": "QEMU did not answer before the monitor command deadline.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `MonitorCommandIndeterminate` | Monitor command result is unknown | The command was sent, but QEMU did not answer in time or the monitor closed first. The ejection may or may not have happened. The error response has `retryable` set to `false`. | Read the VM with the Get a VM operation to inspect the recorded slot before deciding whether to retry. | | `StorageFailed` | Storage operation failed | The VM's record could not be read or written. The error response has `retryable` set to `false`. | Resolve the storage condition before retrying the identical request. | ### Usage ```bash curl --request DELETE \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/cdroms/0' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' }); const vm = await client.vm.vms.ejectCdrom('dev-vm', 0); console.log(vm.data.state); ``` ## Delete a VM `DELETE /api/v1/vm/vms/{name}` Deletes a VM and its associated resources. Deleting a VM is destructive and irreversible. The operation cannot be undone. This endpoint accepts no request body. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `name` | path | `string` | Yes | VM name. It must contain lowercase letters, digits, and `-`, begin with a letter or digit, and be at most 63 characters long. | | `force` | query | `boolean` | No | `force`, `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`. | ### Responses Media type: application/json The VM was deleted. **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `name` | `string` | Yes | Name of the deleted VM. | | `deleted` | `boolean` | Yes | Whether the VM was deleted. | ```json { "name": "dev-vm", "deleted": true } ``` Media type: application/json The VM name or `force` value is invalid. **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `error` | `object` | Yes | Error envelope. | | `error.code` | `string` | Yes | Error code. | | `error.message` | `string` | Yes | Human-readable explanation. | | `error.retryable` | `boolean` | Yes | Whether repeating the identical request could succeed without any other change. | ```json { "error": { "code": "SpecInvalid", "message": "The force parameter must be a boolean value.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `NameInvalid` | Invalid VM name | The name in the path does not match the required VM name format. | Use lowercase letters, digits, and `-`, begin with a letter or digit, and limit the name to 63 characters. | | `SpecInvalid` | Invalid delete request | The request specification is invalid, including an unsupported `force` value. | Omit `force` or use `force=true`, `force=1`, or `0`. | Media type: application/json No VM has the requested name. **Response fields** ```json { "error": { "code": "NotFound", "message": "No VM has this name.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `NotFound` | VM not found | No VM has the requested name. | Confirm the VM name with the List VMs operation. | Media type: application/json The VM cannot be deleted in its current state, another operation is active, or the service cannot verify the VM's run. **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `error` | `object` | Yes | Error envelope. | | `error.code` | `string` | Yes | Error code. | | `error.message` | `string` | Yes | Human-readable explanation. | | `error.retryable` | `boolean` | Yes | Whether repeating the identical request could succeed without any other change. | ```json { "error": { "code": "BadState", "message": "The VM is running and force was not requested.", "retryable": true } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `BadState` | VM cannot be deleted in its current state | The VM is running and `force` was not supplied, or the VM is briefly starting or shutting down. The error response has `retryable` set to `true`. | Stop the VM, or use `force=true` to stop it without asking the guest to shut down. Retry if it is transitioning. | | `OperationInProgress` | Operation in progress | A create, snapshot export setup, start, snapshot, restore, or update owns the VM. | Retry later. | | `Orphaned` | VM run cannot be managed | The service cannot verify the VM's run, or it has blocked the VM after finding multiple possible live runs or an indeterminate delete. The guest may still be running. The error message distinguishes the condition. | For an unverifiable run, check the process, then use `forceAdopt` or `forceMarkDead`; `forceMarkDead` is accepted only when the disk is not locked. For a blocked VM, both actions are refused. Resolve the condition named in the message and restart `hoody-vm`. | Media type: application/json The storage operation failed. **Response fields** ```json { "error": { "code": "StorageFailed", "message": "The storage operation failed.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `StorageFailed` | Storage operation failed | The service could not complete the storage operation. The error response has `retryable` set to `false`. | Resolve the storage condition before retrying the identical request. | ### Usage ```bash curl --request DELETE \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm?force=true' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' }); const deleted = await client.vm.vms.delete('dev-vm', { force: true }); console.log(deleted.data); ```