VM events
Section titled “VM events”This page covers the two Server-Sent Events endpoints for VM changes on one Hoody computer: a stream for a single VM and a stream for every VM the VM service manages. Use them when a caller must react to VM changes as they happen instead of polling getVm. Both endpoints are served by the computer’s VM service, and who may call them is set by the computer’s proxy permission rules. The hostname uses {projectId} and {computerId} to identify the computer, and {server} is the node that serves it.
Event frames
Section titled “Event frames”Both endpoints send Server-Sent Events frames. Every frame carries:
kind: the event name, equal to theevent:line.seq: the VM’s event counter onstateframes. It is0on the uncounted kinds (progress,sidecar,qmp-error,snapshot,share-quota,monitor-stalled,deleted), on thestateframe that ends a create, and on the all-VMs stream’sresync.name: the VM name, on every VM event.vm_id: optional. It is omitted when the VM’s incarnation id is not known.data: the event payload, whose fields depend on the kind.
When a state frame’s data contains seq, it equals the frame’s seq. The state frame that ends a create and the opening frame for a VM with no supervisor have no data.seq and use an outer seq of 0.
The data payload of a state frame is a VM detail with at least name and state. Frames for lifecycle changes may omit spec: keep the configuration you already have, or call getVm when you need the current one. A deleted frame’s data carries name, and lost only when the deletion was found after a gap. A share-quota frame’s data carries over, the new over_quota state, with bytes, quota_bytes and partial from the measurement it was decided on. A monitor-stalled frame’s data carries run and stalled.
deleted and resync are always sent and cannot be named in the events parameter. A comment line arrives every 15 seconds to keep the connection open.
Frames carry no id: line, Last-Event-ID is not honoured, and nothing is replayed. To reconnect, open a new stream: the per-VM stream opens with a state frame describing the VM now, whatever events says, and deleted ends it; the all-VMs stream has no opening state, and deleted does not end it.
Resync
Section titled “Resync”A resync means the client fell behind the bounded buffer and some events were dropped.
On the all-VMs stream, a resync has kind: "resync", seq: 0, scope: "stream", no name, and data with lost (the number of dropped events) and hint. It does not say which VMs were affected, so re-read the VM list and replace the view, because a deletion may have been among the lost events. Detect it by scope or by the absence of name, never by a VM name, since all is a valid VM name.
On the per-VM stream, a resync carries name, vm_id when known, and a seq. It carries data.lost and data.detail, the VM’s current detail, which you apply as the new state; when the state could not be read, it carries data.error and data.hint instead of detail. data.error is an object with code, message and retryable, never a string, so re-read the VM after it. A resync never carries a top-level or data.state field. The seq is data.detail.seq when the detail has one, and otherwise the stream’s last known value, which does not prove the current counter, so process every resync whatever its seq.
Share quota state
Section titled “Share quota state”share.over_quota is the latched state left by the last quota crossing, not a report of whether the last measurement is over quota. It turns true when a measurement exceeds the quota (a partial measurement counts, as a lower bound) and false only when a complete measurement is at or below the return level, quota - quota / 16, or when the quota is removed, so it can stay true below the quota, inside a hysteresis band. Changing the quota re-checks the last measurement and can change the flag. Each change publishes one share-quota event. It is always false when there is no quota.
Stream every VM’s events
Section titled “Stream every VM’s events”GET /api/v1/vm/events
A Server-Sent Events stream of changes to every VM on one connection, including VMs created after it opens, so a create can be watched from before it is requested. It never answers 404, and it opens normally and stays quiet when there are no VMs.
There is no opening snapshot: read listVms for the current set. The events query parameter decides which kinds are sent; deleted and resync cannot be excluded, and here deleted does not end the stream. Events wait in a bounded buffer. If this client reads too slowly and the oldest events are dropped, the server sends one resync with no name, scope: "stream", and the number lost in data.lost. It does not say which events or VMs were lost, so re-read listVms after every resync. Frames carry no id: and nothing is replayed.
The event kinds are the same as on the per-VM stream, GET /api/v1/vm/vms/{name}/events.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
events | query | string | No | Comma-separated event kinds to receive: state, progress, sidecar, qmp-error, snapshot, share-quota, monitor-stalled. Omit the parameter to receive all of them; an empty value (events= with no kinds) is refused with 400, as is an unknown kind. deleted and resync are sent whatever this parameter says, and cannot be named here. |
Response
Section titled “Response”Media type: text/event-stream
The body is a Server-Sent Events stream (text/event-stream), not JSON. A comment is sent every 15 seconds to keep the connection open.
event: statedata: {"kind":"state","seq":42,"name":"dev-vm","vm_id":"0000019a3f5c2e11","data":{"name":"dev-vm","vm_id":"0000019a3f5c2e11","state":"Running","seq":42,"share":{"bytes":1073741824,"partial":false,"sampled_unix":1767225600,"quota_bytes":10737418240,"over_quota":false}}}
event: share-quotadata: {"kind":"share-quota","seq":0,"name":"dev-vm","vm_id":"0000019a3f5c2e11","data":{"over":true,"bytes":11811160064,"quota_bytes":10737418240,"partial":false}}
event: statedata: {"kind":"state","seq":7,"name":"build-agent","vm_id":"0000019a3f5c2e12","data":{"name":"build-agent","vm_id":"0000019a3f5c2e12","state":"Stopped","seq":7,"share":{"bytes":0,"partial":false,"sampled_unix":1767225660,"over_quota":false}}}
event: deleteddata: {"kind":"deleted","seq":0,"name":"build-agent","vm_id":"0000019a3f5c2e12","data":{"name":"build-agent"}}
: keep-aliveA resync on this stream has no name and a scope of stream:
event: resyncdata: {"kind":"resync","seq":0,"scope":"stream","data":{"lost":3,"hint":"re-read GET /vms; this stream fell behind"}}Media type: application/json
The events parameter names an unknown event kind, or the query string carries a parameter this operation does not accept.
{ "error": { "code": "SpecInvalid", "message": "unknown event kind \"unknown-kind\"; choose from [\"state\", \"progress\", \"sidecar\", \"qmp-error\", \"snapshot\", \"share-quota\", \"monitor-stalled\"] (\"deleted\" and \"resync\" are stream protocol and are always delivered)", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
SpecInvalid | Invalid request | The events parameter names an unknown event kind, or the query string carries a parameter this operation does not accept. | Send only the events parameter, using one of state, progress, sidecar, qmp-error, snapshot, share-quota, monitor-stalled. |
Media type: application/json
Too many event streams are open on this service. The limit is 128 streams, shared by both event operations.
{ "error": { "code": "BadState", "message": "too many open event streams (128); close one or poll GET /vms/{name} instead", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BadState | Too many event streams | The service already has 128 open event streams, a limit shared by both event operations. | Close one of the open streams and reconnect, or poll with getVm instead. |
cURL and TypeScript SDK
Section titled “cURL and TypeScript SDK”streamAll() returns a Promise of the stream, so await the call before iterating the frames.
curl -N \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/events?events=state,share-quota'Omit the events parameter to receive every event kind:
curl -N \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/events'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const events = await client.vm.events.streamAll({ events: 'state' });
for await (const frame of events) { if (frame.declared && frame.event === 'resync') { // scope is "stream" and there is no name: re-read the whole VM list continue; } if (frame.declared && frame.event === 'state') { const detail = frame.data.data; console.log(detail.name, frame.data.data.state); }}Building a view of every VM
Section titled “Building a view of every VM”Events say which VM changed, reads say what its state is. Use this design:
- Open the all-VMs stream, then read the VM list with
listVms; the view holds what the list returned.- For any frame that names a VM, whatever its kind, including
deleted, read that VM withgetVm: on 200 replace its row,vm_idincluded; on 404 remove it; on any other error keep the row, mark it stale and read again. - Keep at most one
getVmin flight per name; a frame arriving during the read causes one more read afterwards. - On the all-VMs
resync, read the whole list again. - Order the reads: number each read of a name and each list refresh; apply a read’s result only if no newer read of that name and no list refresh started after it; while a list refresh is in flight, note the names frames arrive for and re-read them after installing the list; a
resyncduring a list refresh starts the refresh over.
- For any frame that names a VM, whatever its kind, including
A state frame may update a display at once, but the read is what the view keeps: other kinds carry no VM detail, and a sampled value such as the shared-folder measurement can be older in a frame than in a read.
A VM leaves the view when getVm answers 404 or when a list refresh no longer contains it; a replacement VM holds the name, so a late deleted for an earlier VM of the same name cannot remove it.
Event-triggered reads do not refresh sampled values such as share, which change without an event, so poll getVm when they must be fresh and show their measurement time, share.sampled_unix.
Stream one VM’s events
Section titled “Stream one VM’s events”GET /api/v1/vm/vms/{name}/events
A Server-Sent Events stream of one VM’s changes, an alternative to polling getVm. Changes are pushed as they happen rather than sampled, so a state that lasts only an instant is still sent unless the filter or the buffer described below drops it.
The server subscribes to the VM’s events first, then reads the VM and sends that state as the first frame, a state event, whatever events says. Because the subscription comes first, a change made while the snapshot is read is not missed, though the filter and the buffer below still apply to it. After the snapshot, events decides which kinds are sent; deleted and resync cannot be excluded. The server skips a change the snapshot already reflects, a non-zero seq not above the snapshot’s seq. Events with seq: 0 are not checked against the snapshot, so process every one you receive.
Events wait in a bounded buffer. If this client reads too slowly and the oldest events are dropped, the server reads the VM again and sends resync with the number lost and the current state, or with error if the state cannot be read; if the VM turns out to be gone, it sends a final deleted with lost instead. deleted ends the stream. Frames carry no id: and nothing is replayed: to reconnect, open a new stream, whose snapshot gives the current state.
monitor-stalled is easy to miss: it carries run and stalled and is sent when QEMU stops responding to control commands and again when it recovers. The VM stays Running throughout, so no state event marks either change. While stalled is true, pause and resume are refused; getVm shows the same fact as monitor_stalled.
The stream follows the VM its snapshot described, identified by vm_id, not by name. If the VM is deleted and a new VM is created with the same name, the new VM’s events are not sent here; a resync that finds the name held by a different VM ends the stream with a deleted for the original one.
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. |
events | query | string | No | Comma-separated event kinds to receive: state, progress, sidecar, qmp-error, snapshot, share-quota, monitor-stalled. Omit the parameter to receive all of them; an empty value (events= with no kinds) is refused with 400, as is an unknown kind. deleted and resync are sent whatever this parameter says, and cannot be named here. The opening state snapshot is sent regardless; the filter applies to the events after it. |
Response
Section titled “Response”Media type: text/event-stream
The body is a Server-Sent Events stream (text/event-stream), not JSON. A comment is sent every 15 seconds to keep the connection open.
event: statedata: {"kind":"state","seq":42,"name":"dev-vm","vm_id":"0000019a3f5c2e11","data":{"name":"dev-vm","vm_id":"0000019a3f5c2e11","state":"Running","seq":42,"share":{"bytes":1073741824,"partial":false,"sampled_unix":1767225600,"quota_bytes":10737418240,"over_quota":false}}}
event: share-quotadata: {"kind":"share-quota","seq":0,"name":"dev-vm","vm_id":"0000019a3f5c2e11","data":{"over":true,"bytes":11811160064,"quota_bytes":10737418240,"partial":false}}
event: resyncdata: {"kind":"resync","seq":43,"name":"dev-vm","vm_id":"0000019a3f5c2e11","data":{"lost":2,"detail":{"name":"dev-vm","vm_id":"0000019a3f5c2e11","state":"Running","seq":43,"share":{"bytes":1610612736,"partial":false,"sampled_unix":1767225660,"quota_bytes":10737418240,"over_quota":false}}}}
event: deleteddata: {"kind":"deleted","seq":0,"name":"dev-vm","vm_id":"0000019a3f5c2e11","data":{"name":"dev-vm"}}A resync that cannot read the VM carries data.error and data.hint instead of data.detail, and repeats the stream’s last known seq, which does not prove the current counter:
event: resyncdata: {"kind":"resync","seq":7,"name":"dev-vm","vm_id":"0000019a3f5c2e11","data":{"lost":1,"error":{"code":"OperationInProgress","message":"vm dev-vm has an operation in progress","retryable":true},"hint":"re-read GET /vms/dev-vm; the current state could not be fetched after this stream fell behind"}}Media type: application/json
The VM name is not valid, or the events parameter names an unknown event kind, or the query string carries a parameter this operation does not accept.
{ "error": { "code": "NameInvalid", "message": "name must start with a lowercase letter or digit, not '-'", "retryable": false }}{ "error": { "code": "SpecInvalid", "message": "unknown event kind \"unknown-kind\"; choose from [\"state\", \"progress\", \"sidecar\", \"qmp-error\", \"snapshot\", \"share-quota\", \"monitor-stalled\"] (\"deleted\" and \"resync\" are stream protocol and are always delivered)", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NameInvalid | Invalid VM name | The VM name is not valid. | Use lowercase letters, digits and -, starting with a letter or digit, at most 63 characters. |
SpecInvalid | Invalid request | The events parameter names an unknown event kind, or the query string carries a parameter this operation does not accept. | Send only the events parameter, using one of state, progress, sidecar, qmp-error, snapshot, share-quota, monitor-stalled. |
Media type: application/json
No VM has this name.
{ "error": { "code": "NotFound", "message": "vm recovery-test does not exist", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NotFound | VM not found | No VM has this name. | Check the name. The event stream never creates a VM. |
Media type: application/json
Too many event streams are open on this service, the VM has just been created and is not ready yet, or the service cannot manage the VM. A VM whose create is still running or has failed is not refused with 409: the stream opens with a state frame whose state is Creating or Failed.
{ "error": { "code": "BadState", "message": "too many open event streams (128); close one or poll GET /vms/{name} instead", "retryable": true }}{ "error": { "code": "OperationInProgress", "message": "vm dev-vm has an operation in progress", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BadState | Too many event streams | The service already has 128 open event streams, a limit shared by both event operations. | Close one of the open streams and reconnect, or poll with getVm. |
OperationInProgress | VM operation in progress | The VM has just been created and is not ready yet. | Retry shortly. |
Orphaned | VM not manageable | The service cannot manage the VM, and the guest may still be running, either because the VM’s run cannot be verified (the recorded process is gone, does not match its record, or the record cannot be read) or because the service has blocked the VM (after a restart it found more than one run that may still be live, or a delete stopped before it could tell whether the VM was removed); the message says which. | For a run that cannot be verified, check the process yourself, then call POST /api/v1/vm/vms/{name}/force-adopt to resume managing it or POST /api/v1/vm/vms/{name}/force-mark-dead to record it as dead, which is accepted only when the VM’s disk is not locked by a running process. For a blocked VM both are refused: resolve the condition the message names, then restart hoody-vm, which settles the VM’s state as it starts. |
cURL and TypeScript SDK
Section titled “cURL and TypeScript SDK”stream() returns a Promise of the stream, so await the call before iterating the frames.
curl -N \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/events?events=state'Omit the events parameter to receive every event kind:
curl -N \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/events'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const events = await client.vm.events.stream('dev-vm', { events: 'state' });
for await (const frame of events) { if (frame.declared && frame.event === 'state') { const detail = frame.data.data; console.log(detail.name, frame.data.data.state); }}