# Displays reference **Page:** kit/displays/reference [Download Raw Markdown](./kit/displays/reference.md) --- # Displays reference Lookup tables for [Hoody Displays](/kit/displays/). Every route and field is in the [API reference](/api/displays/). ## 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](/kit/agent/) web UI at `agent-N` | Normally 4500 + N | | A [virtual machine](/kit/vm/) 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 ignores `displayId`: open the other display's own URL. - **Terminal sessions.** A session with `display: "5"` gets `DISPLAY=:5` in its shell; one opened in the browser at `terminal-5` gets display 5 from the hostname. `POST /api/v1/terminal/create` sets a display only through `display` (alias `display_id`) or `DISPLAY` in `env`, such as `"env": {"DISPLAY": ":5"}`, never from the terminal ID alone. Ephemeral sessions drop any `DISPLAY`. - **`DISPLAY` alone 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_env` on a display whose desktop already runs reuses it. ## 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](#screenshots-and-thumbnails)) | | `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 The [Web Client Interface](/api/displays/web-client/) lists over 50 query parameters, with pages for [UI and theming](/api/displays/ui-theming/) (`dark_mode`, `decorations`, `toolbar`, `floating_menu`, `title_show_hoody`), [performance](/api/displays/performance/), [input and clipboard](/api/displays/input-clipboard/), [sharing](/api/displays/session-sharing/), [feature flags](/api/displays/feature-flags/) and [debugging](/api/displays/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 | 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 | 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 - **Mac keys.** `swap_keys` maps Cmd to Ctrl, so copy and paste keep their usual keys. It is on when the client detects a Mac; `swap_keys=true` forces it, `swap_keys=false` turns 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=false` hides it on a phone. - **Clipboard.** Clipboard sync between your device and the desktop is on by default; `clipboard=false` turns 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 `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_FOUND` though 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 /screenshots` answers 200 with an empty `screenshots` list; other stored reads answer `404 SCREENSHOT_NOT_FOUND` when none is among the newest 500, and thumbnail reads `404 THUMBNAIL_NOT_FOUND` when 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/act` with `screenshotRegion`) has `data` and `mimeType`, no `dataUrl`. - **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 - Every Computer Use, screenshot, window and clipboard route also answers without `/api/v1/display`: `/mouse/click` is `/api/v1/display/mouse/click`. - `displayId` (1 to 999999) wins over the `display-N` host; with neither, `400 NO_DISPLAY_CONTEXT`. - **Mouse buttons:** `1` left, `2` middle, `3` right; `4` to `7` are the wheel (up, down, left, right), and `mouse/scroll` sends one per click. - **Keys** are case-sensitive X11 names: `Return`, `BackSpace`, `Escape`, not `Enter`, `Backspace`, `Esc`. - Every route has a `hoody display ` command; the less obvious: `input type` is `type-at`, `keyboard press` is `keyboard/key`, `windows wait` is `input/wait-until`, `input batch act` is `input/batch`. - The [input API](/api/displays/input-actions/) documents each option, such as `clearModifiers`, `relative` on `window/move`, `useHints` on `window/resize` and `screenshotDelay` on `input/act`. ## 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 - `window/restore` brings back a window minimized by the API, the application or the viewer. `focus` and `raise` do 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/raise` asks the display server to raise a window, which it may not restack. - `restore` does not focus or raise. Next call `window/focus` with `"sync": true` and check `details.inputFocus`: `true` means keyboard focus was observed on the window or a window inside it; an unviewable window can return `false` with a warning. - It waits for the window: `{"success": true, "action": "window-restore", "details": {"windowId": 12345678, "previousState": "iconic", "state": "normal", "synced": true}}`. With `sync`, still minimized after 2 seconds is `409 SYNC_TIMEOUT`. - A window not minimized succeeds with `"previousState": "normal"`, changes nothing and answers `"state": "normal", "synced": true` at once, whatever `sync` says. With `"sync": false`, a minimized window answers `"state": null, "synced": false`. ## 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 - `window-present` needs `pattern`, 1 to 512 characters of extended POSIX regex; `window-absent` takes a `pattern` or an exact `windowId`, not both. `match` (`name` default, `class`, `classname`) and `onlyVisible` belong to a pattern search and are refused with `windowId`. - `timeoutMs` stops at 25,000 because the SDK's transport timeout defaults to 30 seconds. A `pollMs` you send must not exceed `timeoutMs`, but the default 250 is not compared, so a `timeoutMs` under 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: true` unless an earlier consecutive pass with a full five-second budget was inconclusive. `polls` counts completed observations and is zero only when none completed; passes that told nothing are not counted. ## 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](#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 The [input API](/api/displays/input-actions/) 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 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 | 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](/api/computer-operations/) 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.