Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

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.

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.

NameInTypeRequiredDescription
namepathstringYesThe VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters.
cursorquerystringNoThe 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.

Every error status below returns this body shape. Branch on error.code, because error.message is human-readable text and may change.

FieldTypeRequiredDescription
errorobjectYesThe error details.
error.codestringYesThe stable error code for the condition. The possible codes for each status are listed below.
error.messagestringYesA human-readable explanation of the condition.
error.retryablebooleanYesWhether 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-amd64
login: operator
password:

Response headers

HeaderTypeDescription
x-hoody-console-cursorstringPass 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-gapstringnone 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-morebooleantrue 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.
Terminal window
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.

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.

NameInTypeRequiredDescription
namepathstringYesThe VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters.

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.

Every error status below returns this body shape. Branch on error.code, because error.message is human-readable text and may change.

FieldTypeRequiredDescription
errorobjectYesThe error details.
error.codestringYesThe stable error code for the condition. The possible codes for each status are listed below.
error.messagestringYesA human-readable explanation of the condition.
error.retryablebooleanYesWhether 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.

Terminal window
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 @-

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.

NameInTypeRequiredDescription
namepathstringYesThe VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters.
sourcequerystringNoWhich 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".
tailqueryintegerNoNumber 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.

Every error status below returns this body shape. Branch on error.code, because error.message is human-readable text and may change.

FieldTypeRequiredDescription
errorobjectYesThe error details.
error.codestringYesThe stable error code for the condition. The possible codes for each status are listed below.
error.messagestringYesA human-readable explanation of the condition.
error.retryablebooleanYesWhether 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

FieldTypeRequiredDescription
namestringYesThe VM name.
sourcestringYesThe log source: console, qemu, passt, swtpm, or virtiofsd.
linesintegerYesThe number of returned lines.
contentstringYesThe 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.
Terminal window
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'

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.

NameInTypeRequiredDescription
namepathstringYesThe VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters.

This endpoint takes no request body.

Every error status below returns this body shape. Branch on error.code, because error.message is human-readable text and may change.

FieldTypeRequiredDescription
errorobjectYesThe error details.
error.codestringYesThe stable error code for the condition. The possible codes for each status are listed below.
error.messagestringYesA human-readable explanation of the condition.
error.retryablebooleanYesWhether 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

FieldTypeRequiredDescription
reachablebooleanYesAlways true. An agent that does not answer produces a 409 response.
versionstringNoThe 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_commandsarrayNoCommand 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.
warningsarrayYesOne 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.
Terminal window
curl --request GET \
--url 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/demo-vm/agent' \
--header 'Accept: application/json'

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.

NameInTypeRequiredDescription
namepathstringYesThe VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters.

This endpoint takes no request body.

Every error status below returns this body shape. Branch on error.code, because error.message is human-readable text and may change.

FieldTypeRequiredDescription
errorobjectYesThe error details.
error.codestringYesThe stable error code for the condition. The possible codes for each status are listed below.
error.messagestringYesA human-readable explanation of the condition.
error.retryablebooleanYesWhether 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

FieldTypeRequiredDescription
hostnamestringNoThe hostname reported by the guest. Longer values are shortened and marked so that a shortened hostname is not mistaken for a complete one.
osobjectNoOS 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_nsintegerNoThe 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.
interfacesarrayNoNetwork 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.
filesystemsarrayNoMounted 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.
usersarrayNoLogged-in users as reported by the agent. There are at most 256 entries.
warningsarrayYesOne 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.
Terminal window
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'