# VM: Events **Page:** api/vm/events [Download Raw Markdown](./api/vm/events.md) --- # 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 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. ### 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 `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 `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 | 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 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. ```text 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`: ```text event: resync data: {"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. ```json { "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. ```json { "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 `streamAll()` returns a Promise of the stream, so await the call before iterating the frames. ```bash 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: ```bash curl -N \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/events' ``` ```ts 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 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`. ## 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 | 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 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. ```text 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: ```text 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"}} ``` 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. ```json { "error": { "code": "NameInvalid", "message": "name must start with a lowercase letter or digit, not '-'", "retryable": false } } ``` ```json { "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. ```json { "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`. ```json { "error": { "code": "BadState", "message": "too many open event streams (128); close one or poll GET /vms/{name} instead", "retryable": true } } ``` ```json { "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 `stream()` returns a Promise of the stream, so await the call before iterating the frames. ```bash 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: ```bash curl -N \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/events' ``` ```ts 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); } } ```