Displays reference
Section titled “Displays reference”Lookup tables for Hoody Displays. Every route and field is in the API reference.
Display numbers
Section titled “Display numbers”| Source | Display number |
|---|---|
A display-N host, or a terminal at terminal-N | N |
A browser at browser-N | 500 + N |
A desktop at desktop-N | Normally 1600 + N. Opens an Xfce desktop by default, or MATE with ?desktop_env=mate. Use hoody desktop open N. |
The agent web UI at agent-N | Normally 4500 + N |
A virtual machine created with display: "auto" | A free number from 7001 to 8000 by default. A VM picks one only when asked, and never shares a display in use. |
- Each display has its own resolution, window manager state, applications and performance profile.
- Not an access boundary. A request to any display URL of the computer can address another display with
?displayId=. The viewer ignoresdisplayId: open the other display’s own URL. - Terminal sessions. A session with
display: "5"getsDISPLAY=:5in its shell; one opened in the browser atterminal-5gets display 5 from the hostname.POST /api/v1/terminal/createsets a display only throughdisplay(aliasdisplay_id) orDISPLAYinenv, such as"env": {"DISPLAY": ":5"}, never from the terminal ID alone. Ephemeral sessions drop anyDISPLAY. DISPLAYalone creates nothing. A program pointed at a number no session has set up fails to open its window.- One desktop. A session asking for
desktop_envon a display whose desktop already runs reuses it.
Start on first use
Section titled “Start on first use”A session created with a display number sets the display up but normally does not run it. It starts when an API request acts on it, a viewer connects, or a program connects (one started with its DISPLAY set); desktop: true or a desktop_env starts it at once. The first start takes up to about 10 seconds; then it runs until stopped, even after its session ends.
| Request | Starts a display that is not running |
|---|---|
GET /api/v1/display/health, the client page GET /api/v1/display/, GET /windows (answers an empty windows list) | Never |
Stored reads: /screenshots, /screenshot/last, /screenshot/last/info, /screenshot/{timestamp}, /thumbnail/last, /thumbnail/{timestamp} | Never: they answer from captures on disk (404s) |
input/wait | Only with screenshot: true |
input/batch | Only when an entry before the first invalid one acts on the display, so not for only input/wait entries or no valid entry |
input/act | Once valid |
A 400 (a body, region syntax, selection or window-ID format rejected before display access), or an invalid regex in window/search or input/wait-until | No. For the regex, only when its check ran first; otherwise the display may start. A well-formed crop outside the captured screen starts the display and captures before returning 400. In input/act, the action may already have completed. |
A check that needs the running display, such as input/click-at outside the screen | Yes, then 400 |
Any other valid route, including GET /screenshot, GET /api/v1/display/info (root alias: GET /display) and mouse, keyboard and window actions | Yes |
Viewer parameters
Section titled “Viewer parameters”The Web Client Interface lists over 50 query parameters, with pages for UI and theming (dark_mode, decorations, toolbar, floating_menu, title_show_hoody), performance, input and clipboard, sharing, feature flags and debugging. For troubleshooting the viewer, each debug flag (debug_main, debug_keyboard, debug_geometry, debug_mouse, debug_clipboard, debug_draw, debug_audio, debug_network, debug_file) logs that part of it to the browser console.
Quality and bandwidth
Section titled “Quality and bandwidth”| Parameter | Effect |
|---|---|
quality_mode | The viewer’s Image Quality menu: auto (Automatic, default: full quality, lowered while the link is slow when reconnect=true; each adjustment briefly reconnects, and reduced quality is shown as Low bandwidth mode), best (Best quality), reduced (Low bandwidth: lower quality, and still areas are not resent in full quality). |
bandwidth_limit | Bits per second: 1000000 caps a session at 1 Mbps, 500000 at 500 Kbps. |
encoding | Requested on connect. Default webp, which keeps text sharp; auto lets the server choose and can switch busy windows to blurrier video. A choice in the settings dialog applies on Apply & Reconnect. The server picks among encodings both ends support, so any choice, H264 included, depends on the server’s encoders and the browser’s decoders. |
sound=false, video=false | Turn off high-bandwidth features. |
- Bandwidth depends on encoding, resolution and how much of the screen changes (video of moving content costs far more than JPEG updates of a still screen), so measure it.
- Latency follows the network path; the client’s statistics panel shows it. An ordinary link suits coding, editing and browsing, not gaming.
Reconnecting
Section titled “Reconnecting”| Case | Behaviour |
|---|---|
reconnect=true (default), after a connection | Up to 30 retries, one second apart, counted afresh after each success; then reopen the URL. reconnect_count (1 to 1000) sets the 30. |
reconnect=false | No retries on its own; reconnect_count has no effect. Only Start display on the offline card retries, for up to 60 seconds. |
| A viewer that never connected, such as while the display starts | On a display URL of a computer, it shows an offline card with Start display and Open Settings after 3 failed attempts. After more than 30 failed attempts or 90 seconds, it retries every 15 seconds, until 20 minutes after the first attempt. A viewer opened from another address shows the connection settings at that point instead. Set with soft_giveup_attempts, soft_giveup_ms, slow_retry_delay, slow_retry_max_ms. |
A lost connection does not stop the desktop: you lose the view, not the session, and reconnect to its current state.
Keyboard, touch and clipboard
Section titled “Keyboard, touch and clipboard”- Mac keys.
swap_keysmaps Cmd to Ctrl, so copy and paste keep their usual keys. It is on when the client detects a Mac;swap_keys=trueforces it,swap_keys=falseturns it off. - Touch. Touch movement scrolls, taps click, and a virtual keyboard appears when the user agent reads as mobile. A touchscreen laptop needs
keyboard=true;keyboard=falsehides it on a phone. - Clipboard. Clipboard sync between your device and the desktop is on by default;
clipboard=falseturns it off. A browser may block clipboard access: grant the permission or try another browser. Copy and paste inside the desktop always works. - Sharing. Collaboration needs
sharing=true; the display server Hoody starts already allows sharing on its side.
Screenshots and thumbnails
Section titled “Screenshots and thumbnails”GET /screenshot captures a PNG now; base64=true returns JSON (image.data, image.dataUrl, info), region crops and cursor adds the pointer position to the base64 JSON. /screenshot/info captures and returns metadata only. /screenshot/last and /screenshot/last/info read the newest capture, /screenshot/{timestamp} a stored one, and GET /screenshots lists them. /thumbnail captures now at 20%, and /thumbnail/last and /thumbnail/{timestamp} read stored thumbnails, and GET /api/v1/display/info (root alias: GET /display) returns display information with the screenshot list.
- 500 newest. Only the 500 newest captures per display can be listed or looked up. An older one answers
404 SCREENSHOT_NOT_FOUNDthough its file stays on disk: nothing prunes them, they stop being addressable. At one capture a minute that is under nine hours, so fetch what you keep in time, and capture on a schedule if a gallery must stay current. - Not found. With no captures,
GET /screenshotsanswers 200 with an emptyscreenshotslist; other stored reads answer404 SCREENSHOT_NOT_FOUNDwhen none is among the newest 500, and thumbnail reads404 THUMBNAIL_NOT_FOUNDwhen the capture has no thumbnail. - Thumbnails are captures at 20%: 1920x1080 gives 384x216.
- Canvas. Each window is drawn at its screen position on a transparent canvas the size of the screen, so a display with no windows is fully transparent. A window minimized in a viewer is left out.
- Crops. A cropped image (as from
input/actwithscreenshotRegion) hasdataandmimeType, nodataUrl. - Time. Capture work has a 20-second deadline; startup, waiting and cleanup can add time. Cropping has a separate 10-second timeout.
Routes and keys
Section titled “Routes and keys”- Every Computer Use, screenshot, window and clipboard route also answers without
/api/v1/display:/mouse/clickis/api/v1/display/mouse/click. displayId(1 to 999999) wins over thedisplay-Nhost; with neither,400 NO_DISPLAY_CONTEXT.- Mouse buttons:
1left,2middle,3right;4to7are the wheel (up, down, left, right), andmouse/scrollsends one per click. - Keys are case-sensitive X11 names:
Return,BackSpace,Escape, notEnter,Backspace,Esc. - Every route has a
hoody display <group> <action>command; the less obvious:input typeistype-at,keyboard pressiskeyboard/key,windows waitisinput/wait-until,input batch actisinput/batch. - The input API documents each option, such as
clearModifiers,relativeonwindow/move,useHintsonwindow/resizeandscreenshotDelayoninput/act.
Input delivery
Section titled “Input delivery”| Situation | What happens | Do this |
|---|---|---|
| Typing after an API click | A plain mouse/click does not move keyboard focus. input/click-at and input/type-at focus the window they click. | Otherwise window/focus first; it reports details.inputFocus. |
No window manager (desktop: true, no desktop_env) | window/focus still focuses a viewable window, with details.warning that it was not activated or raised. A plain mouse/click elsewhere does not move that focus; input/click-at and input/type-at focus what they click. | window/focus again to type elsewhere. |
| Targeted input | Keyboard actions and mouse/click, double-click, down, up take an optional window; on mouse/move it sets the origin; mouse/move-relative and mouse/scroll do not accept a window target: a supplied window is ignored without an error. Relative movement starts at the pointer; scrolling uses the pointer position or the supplied x and y. Input to a window without focus is a synthetic event, which xterm and others ignore; keyboard/type and keyboard/key then carry details.warning; keyboard/key-down and keyboard/key-up do not report this warning. | Prefer window/focus, then untargeted input. |
| A window minimized in a viewer | It stays hidden after the viewer leaves: window/focus answers details.inputFocus: false, and keys do not reach it: they go to whichever window still has focus, or nowhere. | window/restore, then window/focus; if still false, connect a viewer (a browser tab on the URL) and retry. |
| Pasting a command | Middle click pastes PRIMARY, but POST /clipboard defaults to clipboard. Pasted text does not run even with a final newline: bash 5.1 and later insert it literally. | Write with {"selection": "primary"}, then send {"keys": ["Return"]} to keyboard/key. |
| Dragging | Without steps, drag is one jump, which many applications ignore. steps runs 1 to 1000; 1 is one jump. | At least 2, such as "steps": 8. |
| Held input | holdMs on mouse/down and keyboard/key-down queues a release, which a busy display can delay; if the queue stays full for about a second it is dropped and the input stays held. Without holdMs, it stays held until mouse/up, keyboard/key-up or input/reset. | input/reset when a release matters. |
readonly=true | Blocks input from that browser only. | The HTTP API still takes input. |
| A clipboard read hangs | GET /clipboard returns "" at once when nothing owns the selection. When the display server owns it for an absent viewer, it ends in 503 DISPLAY_NOT_AVAILABLE after 5 seconds (seen with ?selection=primary and clipboard sync off in a viewer). | Write the selection first with POST /clipboard; reads then answer in milliseconds. |
onlyVisible is two tests. On window/search and input/wait-until it keeps viewable windows: a window stays viewable after window/minimize, even once iconic, so minimized windows match and hidden ones (minimized in a viewer) do not. On GET /windows it drops windows with _NET_WM_STATE_HIDDEN, which minimized windows carry.
Minimize and restore
Section titled “Minimize and restore”window/restorebrings back a window minimized by the API, the application or the viewer.focusandraisedo not un-minimize it on the server; with a viewer connected they can make it show the window, so do not rely on them.window/raiseasks the display server to raise a window, which it may not restack.restoredoes not focus or raise. Next callwindow/focuswith"sync": trueand checkdetails.inputFocus:truemeans keyboard focus was observed on the window or a window inside it; an unviewable window can returnfalsewith a warning.- It waits for the window:
{"success": true, "action": "window-restore", "details": {"windowId": 12345678, "previousState": "iconic", "state": "normal", "synced": true}}. Withsync, still minimized after 2 seconds is409 SYNC_TIMEOUT. - A window not minimized succeeds with
"previousState": "normal", changes nothing and answers"state": "normal", "synced": trueat once, whateversyncsays. With"sync": false, a minimized window answers"state": null, "synced": false.
Batches
Section titled “Batches”Actions: mouse/click, mouse/double-click, mouse/move, mouse/move-relative, mouse/down, mouse/up, mouse/scroll, keyboard/type, keyboard/key, keyboard/key-down, keyboard/key-up, input/click-at, input/type-at, input/drag, input/select, input/wait, clipboard/read, clipboard/write, window/focus, window/raise, window/minimize, window/restore, window/move, window/resize, window/close, window/search. input/act takes the same names. params use the standalone route’s schema except for input/wait: nested waits reject screenshot: true. To capture after a nested wait, use input/act with its own screenshot: true.
| Topic | Rule |
|---|---|
| Queue | Mouse, keyboard, input, window and clipboard entries queue one by one, so other input can run between them. Only input/wait entries run outside the queue. |
| 400 | A missing, empty or too long actions; an entry that is not an object, lacks a string action (at most 50 characters) or has a non-object params; malformed JSON; no display context. Over 2 MiB is 413. |
| In the 200 body | Every per-action outcome: unknown name, rejected params, full queue, a window gone, a display not answering. input/act answers an unknown name or rejected params as 400 VALIDATION_ERROR; any other failure keeps its own status and code (400, 429, 404, 409, 500, 503). For input/act and screenshot-bearing input/wait, a screenshot failure can return a non-2xx response after the action or wait completed. Read the response’s action: when it reports completion, do not repeat it. Take a separate screenshot to inspect the result. |
result | clipboard/read: the text as a bare string. window/focus: {inputFocus}, plus warning when focus failed or there is no window manager. window/restore: {windowId, previousState, state, synced}. window/search: IDs. input/click-at: {pointer: {x, y, window}}. keyboard/type, keyboard/key: {warning} for synthetic events to a named window. Others: none. In input/act it is action.result. |
| 60 seconds | Checked before each action: failed.error is Batch timeout exceeded, and skipped lists that action and all later. Checked again at the front of the queue: Command deadline passed while it waited in the queue, and skipped starts after it. An input/wait ending past the budget fails at once: Batch timeout exceeded: the wait would end after the batch budget. Waiting for an action to reach the front of the queue can delay the response well beyond 60 seconds; an expired action is rejected there. Started actions normally run to their own limits, but multiline typing also observes the batch deadline, with at least five seconds from when typing starts. The CLI and SDK time out after 30 seconds by default. Split long CLI batches, or use HTTP or the SDK with a longer request timeout, such as computerClient.display.input.actMany({ actions }, { timeoutMs: 120000 }). If the connection closes, later actions stop. An input action already running finishes; an input/wait ends early. Inspect the display before repeating the batch. |
Window waits
Section titled “Window waits”window-presentneedspattern, 1 to 512 characters of extended POSIX regex;window-absenttakes apatternor an exactwindowId, not both.match(namedefault,class,classname) andonlyVisiblebelong to a pattern search and are refused withwindowId.timeoutMsstops at 25,000 because the SDK’s transport timeout defaults to 30 seconds. ApollMsyou send must not exceedtimeoutMs, but the default 250 is not compared, so atimeoutMsunder 250 alone is one look, not a 400.- Satisfied:
{"success": true, "condition": "window-present", "waitedMs": 1240, "polls": 5, "windows": [83886081]}. Failures keep their status: 503 for a display not answering, 400 for an inconsistent body or bad pattern, 500 otherwise. - Waits take no queue slot; the cap is 4 per display and 16 per service (
429 QUEUE_FULL). - A pass overrunning its share of the time means a busy display and is retried; 503 means an earlier pass overran, or one had a full 5 seconds and did not finish. A timeout ending inside a pass shorter than five seconds returns 200 with
timedOut: trueunless an earlier consecutive pass with a full five-second budget was inconclusive.pollscounts completed observations and is zero only when none completed; passes that told nothing are not counted.
Queue and time limits
Section titled “Queue and time limits”| Limit | Rule |
|---|---|
| Input queue | One command at a time per display, in arrival order, up to 20 waiting; a 21st is 429 QUEUE_FULL. Queue time is not counted against a command. |
| Not queued | input/wait, input/wait-until, GET /windows (including its active-window lookup; it does not use the input queue) and /window/{id}/properties. Screenshot capture, screenshot history and display information also run outside the input queue, so they can run while input is in progress; a screenshot that asks for the cursor position adds a /mouse/location lookup that does queue. Everything else, including the clipboard routes (429 QUEUE_FULL when full), /mouse/location, /window/active, /window/search, window geometry and name, input/reset and input/display-geometry, queues. |
| Per command | Mouse, keyboard, clipboard and window commands stop at 5 seconds each; window/focus is two, so up to about 10. window/move and window/restore: 3.5 seconds with sync (2 waiting for the window manager), 1.5 without. Multiline keyboard/type and input/type-at are exceptions: typing can take up to about 26 seconds, plus display checks, and holds the input queue throughout. Each line has a five-second execution timeout; see request limits. |
sync | A change not seen in time is 409 SYNC_TIMEOUT while the display answers, 503 DISPLAY_NOT_AVAILABLE when not. A mouse move has finished when it answers, so sync adds nothing, and a move to the current point answers at once. |
Request limits
Section titled “Request limits”The input API has every field’s range. These are the ones that combine:
| Field | Rule |
|---|---|
text on keyboard/type, input/type-at | Up to 10,000 characters. Each line must type within 4000 ms (characters times delay, 12 ms when not given, 0 counted as 1): 333 characters per line by default. Its characters times delay, plus 100 ms per line break, must total 25,000 ms or less. Longer is 400 VALIDATION_ERROR naming the largest delay that fits, or asking for several requests. |
repeat on mouse/click, input/click-at; clicks on mouse/scroll | 1 to 100, with delay 0 to 5000 (default 100) after every one, the last included. Count times delay must not exceed 4000 ms (repeat: 100 needs delay: 40 or less), or 400 VALIDATION_ERROR names both; nothing is silently capped. |
keys on keyboard/key | 1 to 20 keysyms or combinations of letters, digits, _, +, -, .. A key named like an input-tool command (exec, type, search and others) is a 400 in any casing. |
| Body | Up to 2 MiB (413 PAYLOAD_TOO_LARGE); malformed JSON is 400 INVALID_JSON. |
Errors
Section titled “Errors”Errors are {"error": ..., "code": ..., "details": {"message": ...}}, and most add details.help, including invalid screenshot-region errors. HTTP 200 input, window and clipboard responses carry success; non-2xx errors use error, code and details instead. Screenshot JSON returns info and image; screenshot listings return display and screenshots; metadata and display-information responses return their data directly. Binary image responses contain the image bytes.
| Status | Code | When |
|---|---|---|
| 400 | VALIDATION_ERROR | A field missing, mistyped or out of range; an unknown action or bad params in input/act |
| 404 | WINDOW_NOT_FOUND | The window does not exist, or the window manager does not manage it |
| 409 | NO_WINDOW_MANAGER | GET /windows, GET /window/active, window/restore, and window/focus on a window that cannot take focus, with no window manager; input/act for those |
| 409 | WINDOW_NOT_VIEWABLE | Untargeted keyboard/type or keyboard/key with no viewable window focused, or click-at / type-at on a point with no viewable window: nothing is sent. Use window/restore and window/focus. keyboard/key-down and keyboard/key-up do not perform this viewability check. |
| 409 | SYNC_TIMEOUT | With "sync": true, the change was sent but not seen in 5 seconds (2 for window/move, window/restore): refused or adjusted, or already so. window/focus, move, resize, minimize, restore, and input/act for them. |
| 429 | QUEUE_FULL | 20 commands waiting, or 4 waits on the display or 16 on the service |
| 500 | INPUT_ACTION_FAILED, CLIPBOARD_FAILED, WINDOW_LIST_FAILED, WINDOW_PROPERTIES_FAILED, SCREENSHOT_FAILED, THUMBNAIL_FAILED, SCREENSHOTS_FAILED, DISPLAY_INFO_FAILED | The input command, a standalone clipboard call, the window list or window properties failed, or a screenshot, thumbnail, screenshot list or display information request failed |
| 503 | DISPLAY_NOT_AVAILABLE | Not running, or a command did not finish in time |
GET /windows returns up to 200 managed windows with windowId, pid (null when none is reported), name, class, desktop, geometry, focused and states. window/search returns IDs, {"success": true, "windows": [83886081]}, and an empty list only means no match. GET /window/active gives {"success": true, "windowId": 83886081}; GET /mouse/location gives {"success": true, "x": 640, "y": 480, "screen": 0, "window": 83886081}.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause | Fix |
|---|---|---|
Window actions answer 409 NO_WINDOW_MANAGER | No desktop started (desktop: true alone starts none), or its window manager exited; retrying does not help | A session on the display with desktop_env xfce or mate. Search, move, geometry, name, mouse, keyboard and window/focus on a viewable window work without one; a batch reports it in failed. |
| The display will not load or is black | Computer stopped, services still starting, or wrong number | Check runtime_info.displays (below). Start a stopped computer; wait and reload, as a first start adds up to about 10 seconds; create a session with that display, since a display exists only after one. |
| The connection drops | Network | Keep reconnect=true, try quality_mode=reduced or another WiFi or cellular link, and check nothing blocks WebSockets. |
| Wrong keys | Layout | swap_keys=true&keyboard_layout=us on a Mac; keyboard_layout=gb, de, fr; keyboard=true for a virtual keyboard. |
| The clipboard does not sync | Off, or blocked by the browser | clipboard=true; grant permission. |
| Lag | Slow link or busy computer | quality_mode=reduced, bandwidth_limit=500000, sound=false&video=false; check load with GET /api/v1/system/resources on terminal-1 (Hoody Terminal). |
| Input does nothing | readonly=true, or proxy permissions | readonly=false. Proxy permissions can block the display service entirely, with no view-only level: check the computer’s. |
| Users disconnect each other | Sharing off | sharing=true&steal=false |
Display state. GET https://api.hoody.com/api/v1/computers/{id}?runtime=true, with your API token, returns the computer in data. In data.runtime_info.displays, find the entry by display and read state: live (running; can be viewed and driven), parked (set up, unused; starts when a viewer connects) or x-live (started, but its viewer service is not running, so it cannot be viewed or captured). pid, the viewer service’s process ID, is absent on parked and x-live and null when unreadable, so judge by state. Computers that do not report state yet omit it. The list holds at most 50 entries and can be empty when the computer was busy, so a missing entry proves nothing.