Connection URL
Authentication
The events WebSocket requires the computer’s password as thetoken query parameter. Retrieve it from the Get VNC Password endpoint before connecting.
Connections without a valid token are rejected with close code 4401.
Query Parameters
Computer password. Retrieve via the Get VNC Password endpoint.
Event Catalog
You can also fetch the event catalog as JSON without a WebSocket connection:Available Event Types
| Type | Description | Detection |
|---|---|---|
window_focus | Active window changed | Polled every 100 ms |
window_open | New window opened | Polled every 100 ms |
window_close | Window closed | Polled every 100 ms |
clipboard | Clipboard content changed | Polled every 250 ms |
file_change | File created, modified, or deleted on Desktop or Downloads | inotify (instant) |
screen_change | Display resolution changed | Polled every 1 s |
audio_stream_start | Audio playback started | Polled every 500 ms |
audio_stream_stop | Audio playback stopped | Polled every 500 ms |
process_start | New process started | Polled every 2 s |
process_stop | Process exited | Polled every 2 s |
idle | No user input for 30 seconds | Polled every 1 s |
active | User input resumed after idle | Polled every 1 s |
Subscription Model
New connections receive no events until they send asubscribe message. This lets you opt in to only the event types you care about, reducing noise and bandwidth.
Subscriptions are:
- Per-connection — each WebSocket connection has its own subscription set
- Additive — subscribe to more types at any time
- Selective — unsubscribe from specific types without disconnecting
Message Protocol
Client → Server Messages
subscribe
subscribe
Start receiving specific event types. You can call this multiple times to add more types.
Must be
"subscribe".Array of event type names to subscribe to. See the event catalog for valid types.
unsubscribe
unsubscribe
ping
ping
Send a heartbeat ping to keep the connection alive.
Server → Client Messages
event
event
A desktop event matching one of your subscribed types.
Always
"event".The event payload.
Event type name (e.g.,
"window_focus", "clipboard").ISO 8601 timestamp of when the event occurred.
Event-specific data. See Event Data Schemas below.
subscribed
subscribed
Confirmation that your subscription was updated.
unsubscribed
unsubscribed
Confirmation that event types were removed from your subscription.
pong
pong
Response to a ping message.
Event Data Schemas
Each event type includes adata object with type-specific fields:
Window events
Clipboard
File changes
/home/user/Desktop and /home/user/Downloads. Detection is via Linux inotify — file events are delivered instantly.
Screen
Audio
Process lifecycle
Idle / Active
Examples
Use Cases
Agent Awareness
Subscribe to
window_focus and idle to give your AI agent context about what the user is doing and when to act.File Monitoring
Watch
file_change events to detect when downloads complete, documents save, or files are created on the Desktop.Clipboard Sync
Monitor
clipboard events to sync clipboard content between the VM and your application in real time.Process Tracking
Use
process_start and process_stop to track application lifecycle — know when Chrome launches, when builds finish, etc.Best Practices
Subscribe Selectively
Only subscribe to event types you need. This reduces message volume and keeps your handler logic simple.
Heartbeat
Send periodic
ping messages (every 30 seconds) to keep the connection alive and detect disconnections early.Handle Backpressure
Events are dropped for slow consumers (buffer size: 256). Process events quickly or offload to a queue.
Reconnection
Implement automatic reconnection with exponential backoff. Re-send your
subscribe message after reconnecting.Events require the computer to be running. If the computer is stopped, the WebSocket connection will be rejected. After reconnecting, you must re-subscribe — subscriptions are not persisted across connections.