Drive TUI applications programmatically: snapshot the rendered screen, search it with regex, press named keys, paste text with bracketed-paste semantics, inject cell-based mouse events, and block on conditions. These endpoints drive a server-side VT parser (libvterm) that mirrors the in-browser xterm.js state, so the view of the screen returned to your automation is the same view a human would see.
Use these endpoints when you need to script terminal applications end to end: testing CLI tools, capturing benchmark output, or building agent-style workflows that observe and act on interactive prompts. Combine wait with snapshot, find, press, paste, and mouse to compose any automation flow without polling or races.
Return a rendered snapshot of the terminal screen as seen by a user. The snapshot includes the visible text grid, cursor position, window title, fullscreen (alt-screen) state, reverse-video highlight spans, and a monotonic sequence counter. On the first call for a session, the VT parser is lazily initialized by replaying the session’s output buffer.
Terminal session ID (numeric 1-65535). On calls routed through a terminal-N containers-proxy hostname, the proxy sets this from the hostname label and overwrites any value you send. Supply it directly only when calling the terminal service without the proxy.
include_colors
query
boolean
No
Include ANSI SGR colored_lines array alongside plain text lines. Default: false
include_highlights
query
boolean
No
Include reverse-video highlight spans. Default: true
scroll_offset
query
integer
No
Lines into scrollback (0 = live viewport). Default: 0
Search the rendered terminal screen (or scrollback) for a PCRE2 regular expression pattern. Returns cell-coordinate hits with matched text. Supports case-insensitive matching, result limits, and scope selection. Pattern length is capped at 1024 bytes and match limits are enforced to prevent ReDoS.
Terminal session ID. On calls routed through a terminal-N containers-proxy hostname, the proxy sets this from the hostname label and overwrites any value you send. Supply it directly only when calling the terminal service without the proxy.
pattern
query
string
Yes
PCRE2 regex pattern to search for (max 1024 bytes).
scope
query
string
No
Search scope: screen, scrollback, or all. Default: screen.
limit
query
integer
No
Maximum number of hits to return. Default: 100, max: 1000.
case_insensitive
query
boolean
No
Case-insensitive matching. Default: false.
scroll_offset
query
integer
No
Scrollback offset for screen scope (0 = live viewport). Default: 0.
Return the full list of key names accepted by POST /api/v1/terminal/press, including aliases and canonical forms. Useful for client-side validation and discoverability. Single printable characters (a-z, 0-9, punctuation) are also accepted but not listed individually.
const client= new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });
awaitclient.terminal.keys.list();
{
"keys":[
"enter",
"tab",
"escape",
"backspace",
"arrow_up",
"ctrl+c",
"f1",
"up",
"esc",
"pgdn",
"c-a",
"s-tab"
],
"count":122,
"notes":"The keys array lists every accepted name — canonical forms (e.g., enter, arrow_up, ctrl+a) followed by alias forms (e.g., up, esc, c-a, s-tab, pgdn, cr, bs). Any single printable ASCII character (0x20-0x7e) is also accepted but not enumerated."
Return global metrics for the server-side VT parser: active vterm session count, memory used and cap in MB, total active wait-waiters across all sessions, and configured limits. Use this to monitor resource usage, tune --vterm-memory-cap-mb, and detect leaks.
Return the VT parser state for a specific session: whether vterm is active, dimensions, update sequence counter, time since last screen change, alt-screen flag, title, scrollback length, and active waiter count. Useful for debugging automation workflows such as investigating why a wait timed out or whether the screen actually changed.
Send one or more named key presses to a terminal session. Keys are encoded through libvterm’s keyboard API which respects the terminal’s current application-cursor mode (DECCKM) and keypad mode (DECKPAM), ensuring correct byte sequences for programs like vim, htop, and tmux. Supports letters, ctrl+letter, arrow keys, function keys, enter, tab, escape, backspace, and more. All keys are validated before any are sent, so a single unknown key rejects the entire request with no partial writes.
Terminal session ID. On calls routed through a terminal-N containers-proxy hostname, the proxy sets this from the hostname label and overwrites any value you send. Supply it directly only when calling the terminal service without the proxy.
Paste text into a terminal session with optional bracketed paste mode. When bracketed=true (default), the text is wrapped in bracketed paste escape sequences if the running program has enabled DECSET 2004 (e.g., vim, zsh). This prevents auto-indent mangling and other paste artifacts. When bracketed=false, the text is sent as raw keystrokes. UTF-8 text including emoji and CJK is fully supported.
Terminal session ID. On calls routed through a terminal-N containers-proxy hostname, the proxy sets this from the hostname label and overwrites any value you send. Supply it directly only when calling the terminal service without the proxy.
Send deterministic mouse events to a terminal session using libvterm’s mouse API. Coordinates are zero-based terminal cells, not pixels. Mouse protocol output is emitted only when the target program has enabled terminal mouse reporting. Events are validated before any are sent, matching the all-or-nothing contract of /press.
Terminal session ID. On calls routed through a terminal-N containers-proxy hostname, the proxy sets this from the hostname label and overwrites any value you send. Supply it directly only when calling the terminal service without the proxy.
Block until a terminal condition is met, then return an atomic snapshot of the screen at the moment of resolution. Supports three modes: stable (no screen updates for debounce_ms), regex (PCRE2 pattern matches on screen), or either (first condition wins). The response includes a full snapshot for the matched, stable, timeout, exited, and search_error statuses so clients avoid a TOCTOU race between wait and a follow-up snapshot call. The vterm_reinit status is the lone exception: it fires when the VT parser was torn down mid-wait and no coherent snapshot can be captured (the client should retry). Maximum 16 concurrent waiters per session.
Terminal session ID. On calls routed through a terminal-N containers-proxy hostname, the proxy sets this from the hostname label and overwrites any value you send. Supply it directly only when calling the terminal service without the proxy.
