# VM: Console, logs and guest agent **Page:** api/vm/console [Download Raw Markdown](./api/vm/console.md) --- # VM: Console, logs and guest agent Use these endpoints to read and write a VM's serial console, inspect run logs, and retrieve status or inventory information reported by the guest agent. The routes run through the Hoody computer that hosts the VM, and the computer's proxy permission rules determine who may call them. Console output and guest-agent reports come from the guest and are not verified. Treat them as untrusted data. The guest-agent endpoints return `409` when the VM is stopped, still booting, or has no available agent. This describes the VM's state, not a fault. ## `GET /api/v1/vm/vms/{name}/console` Reads raw serial console output. Each response contains up to 65536 bytes and includes the `x-hoody-console-cursor`, `x-hoody-console-gap`, and `x-hoody-console-more` headers. Pass the returned `x-hoody-console-cursor` value back as `cursor` to continue reading. The cursor is opaque and must not be edited. Console bytes are returned exactly as the guest wrote them, so decode the concatenated stream rather than decoding each response separately. ### 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. | | `cursor` | query | string | No | The `x-hoody-console-cursor` value from a previous read. Omit it or send it empty to start at the beginning of the current run's output. The value is opaque and must not be built or edited. | This endpoint takes no request body. ### Responses Every error status below returns this body shape. Branch on `error.code`, because `error.message` is human-readable text and may change. | Field | Type | Required | Description | |---|---|---|---| | `error` | object | Yes | The error details. | | `error.code` | string | Yes | The stable error code for the condition. The possible codes for each status are listed below. | | `error.message` | string | Yes | A human-readable explanation of the condition. | | `error.retryable` | boolean | Yes | Whether repeating the identical request could succeed without any other change. | Media type: application/octet-stream The response contains up to 65536 bytes of console output, possibly none. Check `x-hoody-console-gap` before using the body because it reports whether output was lost since the previous read. The body is raw bytes. This example is decoded as ASCII for readability: ```text Linux version 6.1.0-18-amd64 login: operator password: ``` **Response headers** | Header | Type | Description | |---|---|---| | `x-hoody-console-cursor` | string | Pass this value back as `cursor` to continue. It always points past the returned bytes, including when the gap header reports lost output. | | `x-hoody-console-gap` | string | `none` means the read continues exactly from the previous read. `truncated` means the console log reached its 8 MiB limit and an unknown number of bytes was discarded, so this read resumes from the oldest retained output. `run-changed` means the VM restarted after the cursor was issued, so this read starts at the beginning of the current run. | | `x-hoody-console-more` | boolean | `true` means more output was already waiting after the returned bytes, so read again immediately. `false` means the read caught up when the response was produced, although more output may arrive later. | Media type: application/json The VM name is invalid, or the cursor or query string is invalid. ```json { "error": { "code": "SpecInvalid", "message": "The cursor was not issued by this service.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `NameInvalid` | Invalid VM name | The VM name does not satisfy the required naming rules. | Use a name containing only lowercase letters, digits, or `-`, starting with a letter or digit and no longer than 63 characters. | | `SpecInvalid` | Invalid request | The cursor was not issued by this service, or the query string contains an unsupported parameter. | Remove unsupported query parameters and pass a cursor exactly as returned by the service. | Media type: application/json No VM has this name, or the VM has never run. ```json { "error": { "code": "NotFound", "message": "No VM named 'demo-vm' was found.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `NotFound` | VM not found | No VM has the requested name, or the VM has never run. | Check the VM name and whether the VM has been run. | Media type: application/json `BadState` means the VM was created without `console`. `OperationInProgress` means the VM is still being created or has just been created and is not ready to be managed yet. `Orphaned` means the service cannot manage the VM, although the guest may still be running. An `Orphaned` response distinguishes a run that cannot be verified from a blocked VM. For a run that cannot be verified, check the process, then call `forceAdopt` to resume managing it or `forceMarkDead` to record it as dead. `forceMarkDead` is accepted only when the VM's disk is not locked by a running process. For a blocked VM, both operations are refused. Resolve the condition named by `error.message`, then restart `hoody-vm`. ```json { "error": { "code": "OperationInProgress", "message": "The VM is still being created. Retry shortly.", "retryable": true } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `BadState` | Invalid VM state | The VM was created without `console`. | Use a VM configured with `console`. | | `OperationInProgress` | Operation in progress | The VM is still being created or is not yet ready to be managed. | Retry shortly after creation finishes. | | `Orphaned` | VM run cannot be managed | The guest may still be running, but the service cannot verify or manage its recorded run. The message distinguishes an unverifiable run from a VM blocked after a restart found multiple potentially live runs or a delete could not determine whether the VM was removed. | For an unverifiable run, check the process, then call `forceAdopt` or `forceMarkDead`. For a blocked VM, resolve the condition named in `error.message`, then restart `hoody-vm`. | Media type: application/json The service could not read storage or save the launch record. ```json { "error": { "code": "StorageFailed", "message": "The storage operation failed.", "retryable": true } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `StorageFailed` | Storage operation failed | The VM's storage operation failed. | Retry after the storage problem is resolved. | | `JournalFailed` | Launch record not saved | The launch record could not be saved. | Retry after the journal problem is resolved. | ### Usage ```bash curl --request GET --dump-header - \ --url 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/demo-vm/console' \ --header 'Accept: application/octet-stream' ``` `--dump-header -` prints the response headers before the body. To continue a read, pass the exact `x-hoody-console-cursor` response header value as the `cursor` query parameter. ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' }); // console.read returns only the body; the cursor arrives in the x-hoody-console-cursor header let cursor: string | undefined; client.http.use({ onResponse: (ctx) => { const next = ctx.response.headers.get('x-hoody-console-cursor'); if (next) cursor = next; }, }); const name = 'demo-vm'; const first = await client.vm.console.read(name); if (!cursor) { throw new Error('The console response did not include a cursor.'); } const more = await client.vm.console.read(name, { cursor }); ``` `console.read` returns only the body. The cursor is the `x-hoody-console-cursor` response header, so read it with a response middleware, as above (it sees every response this client receives), or with a plain `fetch`, then pass it as `{ cursor }` on the next read. ## `POST /api/v1/vm/vms/{name}/console` Writes raw bytes to the VM's serial input. The service sends between 1 and 4096 bytes exactly as supplied. Nothing is added, so end a command with its own newline. Control characters can be sent as themselves, such as `0x03` for Ctrl-C and `0x04` for Ctrl-D. A successful response confirms that the bytes were sent to the serial port, but not that the guest read them. Read the console to observe the effect. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `name` | path | string | Yes | The VM name: lowercase letters, digits and `-`, starting with a letter or digit, at most 63 characters. | ### Request body The request body contains raw bytes with media type `application/octet-stream`. It must contain at least 1 byte and at most 4096 bytes. The body is sent exactly as given, and the `Content-Type` header is ignored. A JSON body is therefore sent as its literal text. The service does not append a newline or alter control characters. ### Responses Every error status below returns this body shape. Branch on `error.code`, because `error.message` is human-readable text and may change. | Field | Type | Required | Description | |---|---|---|---| | `error` | object | Yes | The error details. | | `error.code` | string | Yes | The stable error code for the condition. The possible codes for each status are listed below. | | `error.message` | string | Yes | A human-readable explanation of the condition. | | `error.retryable` | boolean | Yes | Whether repeating the identical request could succeed without any other change. | Media type: none All bytes were sent to the guest's serial port, but this does not confirm that the guest read them. The response has no body. Media type: application/json The VM name is invalid, the body is empty or larger than 4096 bytes, or the request contains an unsupported query parameter. ```json { "error": { "code": "SpecInvalid", "message": "The request body must contain between 1 and 4096 bytes.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `NameInvalid` | Invalid VM name | The VM name does not satisfy the required naming rules. | Use a name containing only lowercase letters, digits, or `-`, starting with a letter or digit and no longer than 63 characters. | | `SpecInvalid` | Invalid request | The body is empty, the body is larger than 4096 bytes, or the request contains an unsupported query parameter. | Send between 1 and 4096 bytes and remove unsupported query parameters. | Media type: application/json No VM has this name. ```json { "error": { "code": "NotFound", "message": "No VM named 'demo-vm' was found.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `NotFound` | VM not found | No VM has the requested name. | Check the VM name. | Media type: application/json The request body stopped arriving for 30 seconds, or took longer than 30 seconds in total. Nothing was written, so the request can be sent again. ```json { "error": { "code": "RequestBodyStalled", "message": "The request body stopped arriving before it was complete.", "retryable": true } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `RequestBodyStalled` | Request body stalled | The request body stopped arriving, and nothing was written to the guest. | Send the request again. | Media type: application/json `BadState` means the VM was created without `console` or `console_input`. `OperationInProgress` means another console write is still in progress or the VM is still being created. `Orphaned` means the service cannot manage the VM, although the guest may still be running. An `Orphaned` response distinguishes a run that cannot be verified from a blocked VM. For a run that cannot be verified, check the process, then call `forceAdopt` to resume managing it or `forceMarkDead` to record it as dead. `forceMarkDead` is accepted only when the VM's disk is not locked by a running process. For a blocked VM, both operations are refused. Resolve the condition named by `error.message`, then restart `hoody-vm`. ```json { "error": { "code": "OperationInProgress", "message": "Another console write is still in progress. Retry after it finishes.", "retryable": true } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `BadState` | Invalid VM state | The VM was created without `console` or `console_input`. | Use a VM configured with console input. | | `OperationInProgress` | Operation in progress | Another console write is still running, or the VM is still being created. | Retry after the current operation or creation finishes. | | `Orphaned` | VM run cannot be managed | The guest may still be running, but the service cannot verify or manage its recorded run. The message distinguishes an unverifiable run from a VM blocked after a restart found multiple potentially live runs or a delete could not determine whether the VM was removed. | For an unverifiable run, check the process, then call `forceAdopt` or `forceMarkDead`. For a blocked VM, resolve the condition named in `error.message`, then restart `hoody-vm`. | Media type: application/json The write may have been delivered partially, or the service could not read the VM's stored configuration. ```json { "error": { "code": "ConsoleDeliveryIndeterminate", "message": "The console write failed after some bytes were sent.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `ConsoleDeliveryIndeterminate` | Console delivery indeterminate | The write failed partway, so some bytes may have reached the guest. | Read the console before resending, or the guest may receive the input twice. | | `StorageFailed` | Storage operation failed | The VM's stored configuration could not be read. Nothing was written. | Retry after storage recovers. | Media type: application/json The guest's serial console is not connected. Nothing was written, so the request is safe to resend. ```json { "error": { "code": "ConsoleUnavailable", "message": "The guest serial console is not connected.", "retryable": true } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `ConsoleUnavailable` | Console unavailable | The connection to the guest's serial console is not established, either because it is not connected yet or because it has already closed for this run. Nothing was written. | Retry when the console connection is available. | ### Usage ```bash printf 'echo ready\n' | curl --request POST \ --url 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/demo-vm/console' \ --header 'Content-Type: application/octet-stream' \ --data-binary @- ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' }); const name = 'demo-vm'; const data = new TextEncoder().encode('echo ready\n'); await client.vm.console.write(name, data); ``` The `data` object contains the exact raw bytes to send. The service does not append a newline or alter control characters. ## `GET /api/v1/vm/vms/{name}/log` Reads lines from the end of a VM log. With `source=console`, this returns the guest's serial console output after sanitising each line. Each console line is limited to 512 characters. When a line is cut, `…` is added as character 513 to mark the cut. The text remains untrusted because it is chosen by the guest. ### 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. | | `source` | query | string | No | Which log to read. Allowed values are `console`, `qemu`, `passt`, `swtpm`, and `virtiofsd`. `console` is the guest's serial console output, sanitised per line. `qemu` is the hypervisor's error output. `passt`, `swtpm`, and `virtiofsd` are the networking, virtual TPM, and shared-folder helper processes. Read a helper log when `sidecars` in the VM details reports it as `degraded`. Default: `"console"`. | | `tail` | query | integer | No | Number of lines to return, counted from the end of the log. Values from 10001 through 18446744073709551615 are treated as 10000. A larger value is refused with 400 `SpecInvalid`. Default: `200`. | This endpoint takes no request body. ### Responses Every error status below returns this body shape. Branch on `error.code`, because `error.message` is human-readable text and may change. | Field | Type | Required | Description | |---|---|---|---| | `error` | object | Yes | The error details. | | `error.code` | string | Yes | The stable error code for the condition. The possible codes for each status are listed below. | | `error.message` | string | Yes | A human-readable explanation of the condition. | | `error.retryable` | boolean | Yes | Whether repeating the identical request could succeed without any other change. | Media type: application/json The response contains the last lines of the selected log. ```json { "name": "demo-vm", "source": "console", "lines": 3, "content": "login: operator\ndemo-vm:~$ uptime\n 12:01:03 up 4 min, 1 user, load average: 0.02, 0.01, 0.00" } ``` **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `name` | string | Yes | The VM name. | | `source` | string | Yes | The log source: `console`, `qemu`, `passt`, `swtpm`, or `virtiofsd`. | | `lines` | integer | Yes | The number of returned lines. | | `content` | string | Yes | The returned lines joined with newlines. For `source=console`, escape sequences, C0 and C1 control characters, bidirectional overrides, and invisible characters are removed per line. Each console line is limited to 512 characters. When a line is cut, `…` is added as character 513 to mark the cut. The text and non-ASCII scripts are retained, but the content remains untrusted. | Media type: application/json The VM name is invalid, the `source` value is unsupported, `tail` is not a non-negative integer no greater than 18446744073709551615, a parameter is duplicated, or the query string contains an unsupported parameter. ```json { "error": { "code": "SpecInvalid", "message": "The tail value must be a non-negative integer no greater than 18446744073709551615.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `NameInvalid` | Invalid VM name | The VM name does not satisfy the required naming rules. | Use a name containing only lowercase letters, digits, or `-`, starting with a letter or digit and no longer than 63 characters. | | `SpecInvalid` | Invalid request | The `source` value is unsupported, `tail` is not a non-negative integer or is greater than 18446744073709551615, a parameter is duplicated, or the query string contains an unsupported parameter. Values from 10001 through 18446744073709551615 are treated as 10000. | Use a supported `source`, provide a valid `tail`, and remove duplicate or unsupported query parameters. | Media type: application/json No VM has this name, the VM has never run, or the selected log does not exist for its latest run. ```json { "error": { "code": "NotFound", "message": "No log named 'console' exists for this VM's latest run.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `NotFound` | Log not found | No VM has the requested name, the VM has never run, or the selected log does not exist for its latest run. | Check the VM name, run history, and selected `source`. | Media type: application/json `OperationInProgress` means another VM operation is in progress. `BadState` means the VM is in the wrong state for the command. `Orphaned` means the service cannot manage the VM, although the guest may still be running. An `Orphaned` response distinguishes a run that cannot be verified from a blocked VM. For a run that cannot be verified, check the process, then call `forceAdopt` to resume managing it or `forceMarkDead` to record it as dead. `forceMarkDead` is accepted only when the VM's disk is not locked by a running process. For a blocked VM, both operations are refused. Resolve the condition named by `error.message`, then restart `hoody-vm`. ```json { "error": { "code": "OperationInProgress", "message": "Another operation is in progress. Retry after it finishes.", "retryable": true } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `OperationInProgress` | Operation in progress | Another operation is in progress. | Retry after the current operation finishes. | | `BadState` | Invalid VM state | The VM is in the wrong state for this command. | Resolve the state named in `error.message` before retrying. | | `Orphaned` | VM run cannot be managed | The guest may still be running, but the service cannot verify or manage its recorded run. The message distinguishes an unverifiable run from a VM blocked after a restart found multiple potentially live runs or a delete could not determine whether the VM was removed. | For an unverifiable run, check the process, then call `forceAdopt` or `forceMarkDead`. For a blocked VM, resolve the condition named in `error.message`, then restart `hoody-vm`. | Media type: application/json The service could not read storage or save the launch record. ```json { "error": { "code": "StorageFailed", "message": "The storage operation failed.", "retryable": true } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `StorageFailed` | Storage operation failed | The VM's storage operation failed. | Retry after the storage problem is resolved. | | `JournalFailed` | Launch record not saved | The launch record could not be saved. | Retry after the journal problem is resolved. | ### Usage ```bash curl --get \ --url 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/demo-vm/log' \ --data-urlencode 'source=console' \ --data-urlencode 'tail=200' \ --header 'Accept: application/json' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' }); const name = 'demo-vm'; const result = await client.vm.vms.getLogs(name, { source: 'console', tail: 200 }); ``` ## `GET /api/v1/vm/vms/{name}/agent` Checks whether the guest agent answered. A successful response has `reachable: true`. An unavailable agent produces a `409` response instead. The version and supported-command list are claims made by the guest, not verified service capabilities. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `name` | path | string | Yes | The VM name: lowercase letters, digits and `-`, starting with a letter or digit, at most 63 characters. | This endpoint takes no request body. ### Responses Every error status below returns this body shape. Branch on `error.code`, because `error.message` is human-readable text and may change. | Field | Type | Required | Description | |---|---|---|---| | `error` | object | Yes | The error details. | | `error.code` | string | Yes | The stable error code for the condition. The possible codes for each status are listed below. | | `error.message` | string | Yes | A human-readable explanation of the condition. | | `error.retryable` | boolean | Yes | Whether repeating the identical request could succeed without any other change. | Media type: application/json The guest agent answered. ```json { "reachable": true, "version": "1.8.2", "supported_commands": [ "guest-info" ], "warnings": [] } ``` **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `reachable` | boolean | Yes | Always `true`. An agent that does not answer produces a `409` response. | | `version` | string | No | The agent's version string as reported by the guest. Control characters are removed and the value is length-limited. The field is absent when the agent reported no version. | | `supported_commands` | array | No | Command names listed by the agent in its `guest-info` answer, including commands the service does not use and commands the agent marks as disabled. There are at most 256 entries. Entries that are not plain command names are dropped, and the field is absent when no usable entry was returned. | | `warnings` | array | Yes | One line for each change made to the agent's answer, including the original entry count when more than 256 commands were listed and the number of unusable names that were dropped. An empty array means the command list is complete. | Media type: application/json The VM name is invalid, or the request contains an unsupported query parameter. ```json { "error": { "code": "NameInvalid", "message": "The VM name is invalid.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `NameInvalid` | Invalid VM name | The VM name does not satisfy the required naming rules. | Use a name containing only lowercase letters, digits, or `-`, starting with a letter or digit and no longer than 63 characters. | | `SpecInvalid` | Invalid request | The request contains a query parameter that this operation does not accept. | Remove the unsupported query parameter. | Media type: application/json No VM has this name. ```json { "error": { "code": "NotFound", "message": "No VM named 'demo-vm' was found.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `NotFound` | VM not found | No VM has the requested name. | Check the VM name. | Media type: application/json `BadState` means the VM is not running, has no guest-agent channel, or no agent answered. This can occur while the VM is booting or when no agent is installed. `OperationInProgress` means the VM is still being created or has just been created and is not ready to be managed yet. `Orphaned` means the service cannot manage the VM, although the guest may still be running. A `409` from this endpoint describes the VM's current state, not a fault. An `Orphaned` response distinguishes a run that cannot be verified from a blocked VM. For a run that cannot be verified, check the process, then call `forceAdopt` to resume managing it or `forceMarkDead` to record it as dead. `forceMarkDead` is accepted only when the VM's disk is not locked by a running process. For a blocked VM, both operations are refused. Resolve the condition named by `error.message`, then restart `hoody-vm`. ```json { "error": { "code": "BadState", "message": "The VM is running, but no guest agent answered.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `BadState` | Invalid VM state | The VM is not running, has no guest-agent channel, or no agent answered. The condition can occur while booting or when no agent is installed. | Read `error.message`, then wait for a running VM with an available agent or provide an agent where required. | | `OperationInProgress` | Operation in progress | The VM is still being created or is not yet ready to be managed. | Retry shortly after creation finishes. | | `Orphaned` | VM run cannot be managed | The guest may still be running, but the service cannot verify or manage its recorded run. The message distinguishes an unverifiable run from a VM blocked after a restart found multiple potentially live runs or a delete could not determine whether the VM was removed. | For an unverifiable run, check the process, then call `forceAdopt` or `forceMarkDead`. For a blocked VM, resolve the condition named in `error.message`, then restart `hoody-vm`. | Media type: application/json The VM's storage operation failed. ```json { "error": { "code": "StorageFailed", "message": "The storage operation failed.", "retryable": true } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `StorageFailed` | Storage operation failed | The VM's storage operation failed. | Retry after the storage problem is resolved. | ### Usage ```bash curl --request GET \ --url 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/demo-vm/agent' \ --header 'Accept: application/json' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' }); const name = 'demo-vm'; const result = await client.vm.guestAgent.get(name); ``` ## `GET /api/v1/vm/vms/{name}/agent/inventory` Returns inventory information reported by the guest agent. Every section is optional. A section is absent when the agent does not support it, refuses it, times out before it is asked, or returns the wrong JSON type. The `warnings` array explains missing or shortened sections. All values are reported by the guest, not measured by the service. Every string, including nested values, array elements, and object keys, is cut to 512 characters, with `…` added as character 513 to mark the cut. The service also replaces presentation-affecting control and invisible characters, limits object sizes and nested array lengths, and replaces values nested more than 8 levels deep with `null`. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `name` | path | string | Yes | The VM name: lowercase letters, digits and `-`, starting with a letter or digit, at most 63 characters. | This endpoint takes no request body. ### Responses Every error status below returns this body shape. Branch on `error.code`, because `error.message` is human-readable text and may change. | Field | Type | Required | Description | |---|---|---|---| | `error` | object | Yes | The error details. | | `error.code` | string | Yes | The stable error code for the condition. The possible codes for each status are listed below. | | `error.message` | string | Yes | A human-readable explanation of the condition. | | `error.retryable` | boolean | Yes | Whether repeating the identical request could succeed without any other change. | Media type: application/json The response contains the sections answered by the guest agent. Sections that were not answered are absent and explained in `warnings`. ```json { "hostname": "demo-vm", "os": { "id": "debian", "name": "Debian GNU/Linux", "version": "12", "kernel-release": "6.1.0-18-amd64", "machine": "x86_64" }, "time_ns": 1735689600000000000, "interfaces": [ { "name": "eth0", "mac": "52:54:00:12:34:56", "addresses": [ "192.0.2.10/24" ] } ], "filesystems": [ { "mount": "/", "device": "/dev/vda1", "type": "ext4", "used_bytes": 3221225472, "total_bytes": 10737418240 } ], "users": [ { "name": "operator", "tty": "pts/0" } ], "warnings": [] } ``` **Response fields** | Field | Type | Required | Description | |---|---|---|---| | `hostname` | string | No | The hostname reported by the guest. Longer values are shortened and marked so that a shortened hostname is not mistaken for a complete one. | | `os` | object | No | OS information passed through as reported by the agent. It commonly contains `id`, `name`, `version`, `kernel-release`, and `machine`, although keys are chosen by the guest. The object has at most 64 keys. | | `time_ns` | integer | No | The guest clock in nanoseconds since the Unix epoch, represented as a 64-bit integer. A large difference from the host clock can cause TLS connections inside the guest to fail. | | `interfaces` | array | No | Network interfaces with their MAC and IP addresses as reported by the agent. The guest's DHCP-assigned address appears here. There are at most 64 entries. | | `filesystems` | array | No | Mounted filesystems and the used and total bytes reported by the guest. There are at most 128 entries. The shared folder never appears in this list, whether mounted or not. | | `users` | array | No | Logged-in users as reported by the agent. There are at most 256 entries. | | `warnings` | array | Yes | One line for each missing, shortened, or dropped section. It includes the agent's reason for a refused section, `not asked` for sections after the agent stopped responding, the original count for a truncated list, and the unexpected JSON type. An empty array means every section was returned in full. | Media type: application/json The VM name is invalid, or the request contains an unsupported query parameter. ```json { "error": { "code": "NameInvalid", "message": "The VM name is invalid.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `NameInvalid` | Invalid VM name | The VM name does not satisfy the required naming rules. | Use a name containing only lowercase letters, digits, or `-`, starting with a letter or digit and no longer than 63 characters. | | `SpecInvalid` | Invalid request | The request contains a query parameter that this operation does not accept. | Remove the unsupported query parameter. | Media type: application/json No VM has this name. ```json { "error": { "code": "NotFound", "message": "No VM named 'demo-vm' was found.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `NotFound` | VM not found | No VM has the requested name. | Check the VM name. | Media type: application/json `BadState` means the VM is not running, has no guest-agent channel, or no agent answered. This can occur while the VM is booting or when no agent is installed. `OperationInProgress` means the VM is still being created or has just been created and is not ready to be managed yet. `Orphaned` means the service cannot manage the VM, although the guest may still be running. A `409` from this endpoint describes the VM's current state, not a fault. An `Orphaned` response distinguishes a run that cannot be verified from a blocked VM. For a run that cannot be verified, check the process, then call `forceAdopt` to resume managing it or `forceMarkDead` to record it as dead. `forceMarkDead` is accepted only when the VM's disk is not locked by a running process. For a blocked VM, both operations are refused. Resolve the condition named by `error.message`, then restart `hoody-vm`. ```json { "error": { "code": "BadState", "message": "The VM is running, but no guest agent answered.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `BadState` | Invalid VM state | The VM is not running, has no guest-agent channel, or no agent answered. The condition can occur while booting or when no agent is installed. | Read `error.message`, then wait for a running VM with an available agent or provide an agent where required. | | `OperationInProgress` | Operation in progress | The VM is still being created or is not yet ready to be managed. | Retry shortly after creation finishes. | | `Orphaned` | VM run cannot be managed | The guest may still be running, but the service cannot verify or manage its recorded run. The message distinguishes an unverifiable run from a VM blocked after a restart found multiple potentially live runs or a delete could not determine whether the VM was removed. | For an unverifiable run, check the process, then call `forceAdopt` or `forceMarkDead`. For a blocked VM, resolve the condition named in `error.message`, then restart `hoody-vm`. | Media type: application/json The VM's storage operation failed. ```json { "error": { "code": "StorageFailed", "message": "The storage operation failed.", "retryable": true } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `StorageFailed` | Storage operation failed | The VM's storage operation failed. | Retry after the storage problem is resolved. | ### Usage ```bash curl --request GET \ --url 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/demo-vm/agent/inventory' \ --header 'Accept: application/json' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' }); const name = 'demo-vm'; const result = await client.vm.guestAgent.getInventory(name); ```