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

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.

Both endpoints send Server-Sent Events frames. Every frame carries:

  • kind: the event name, equal to the event: line.
  • seq: the VM’s event counter on state frames. It is 0 on the uncounted kinds (progress, sidecar, qmp-error, snapshot, share-quota, monitor-stalled, deleted), on the state frame that ends a create, and on the all-VMs stream’s resync.
  • 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.

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.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.

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.

NameInTypeRequiredDescription
eventsquerystringNoComma-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.

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: state
data: {"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-quota
data: {"kind":"share-quota","seq":0,"name":"dev-vm","vm_id":"0000019a3f5c2e11","data":{"over":true,"bytes":11811160064,"quota_bytes":10737418240,"partial":false}}
event: state
data: {"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: deleted
data: {"kind":"deleted","seq":0,"name":"build-agent","vm_id":"0000019a3f5c2e12","data":{"name":"build-agent"}}
: keep-alive

A resync on this stream has no name and a scope of stream:

event: resync
data: {"kind":"resync","seq":0,"scope":"stream","data":{"lost":3,"hint":"re-read GET /vms; this stream fell behind"}}

streamAll() returns a Promise of the stream, so await the call before iterating the frames.

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

Terminal window
curl -N \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/events'

Events say which VM changed, reads say what its state is. Use this design:

  1. 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 with getVm: on 200 replace its row, vm_id included; on 404 remove it; on any other error keep the row, mark it stale and read again.
    • Keep at most one getVm in 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 resync during a list refresh starts the refresh over.

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.

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.

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

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: state
data: {"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-quota
data: {"kind":"share-quota","seq":0,"name":"dev-vm","vm_id":"0000019a3f5c2e11","data":{"over":true,"bytes":11811160064,"quota_bytes":10737418240,"partial":false}}
event: resync
data: {"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: deleted
data: {"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: resync
data: {"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"}}

stream() returns a Promise of the stream, so await the call before iterating the frames.

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

Terminal window
curl -N \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/events'