VM: Console, logs and guest agent
Section titled “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.
GET /api/v1/vm/vms/{name}/console
Section titled “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
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | Yes | The VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters. |
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
Section titled “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:
Linux version 6.1.0-18-amd64login: operatorpassword: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.
{ "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.
{ "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.
{ "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.
{ "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. |
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.
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 headerlet 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
Section titled “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
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | Yes | The VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters. |
Request body
Section titled “Request body”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
Section titled “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.
{ "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.
{ "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.
{ "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.
{ "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.
{ "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.
{ "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. |
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 @-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
Section titled “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
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | Yes | The VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters. |
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
Section titled “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.
{ "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.
{ "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.
{ "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.
{ "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.
{ "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. |
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'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
Section titled “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
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | Yes | The VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters. |
This endpoint takes no request body.
Responses
Section titled “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.
{ "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.
{ "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.
{ "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.
{ "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.
{ "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. |
curl --request GET \ --url 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/demo-vm/agent' \ --header 'Accept: application/json'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
Section titled “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
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | Yes | The VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters. |
This endpoint takes no request body.
Responses
Section titled “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.
{ "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.
{ "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.
{ "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.
{ "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.
{ "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. |
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'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);