Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

Lookup tables for Hoody Terminal. Every route and field is in the API reference.

  • New sessions take ids 1 to 9999. Terminal URLs above 9999, and ids 4501 to 5000 reserved for agents, answer 404 SERVICE_INDEX_OUT_OF_RANGE.
  • Ephemeral sessions get ids from 5001 to 7999, which are ordinary ids: terminal-5001 addresses session 5001.
  • How many run at once depends on the computer’s resources.
  • The hostname decides. On a terminal-N hostname, Hoody Proxy sets the query terminal_id to N and overwrites any value you send. Only the POST /api/v1/terminal/create body field and {terminal_id} path parameters are yours, and they must name the host’s terminal.

These apply only when a session’s shell starts, on a terminal number with no session or with reset=true, and are ignored on a running shell.

SettingNotes
shellbash (default), zsh, fish, sh, or tmux in the browser.
userThe account the shell runs as, in the create body or the execute query. For sudo, run as root or as a user with sudo rights. Consider separate computers for privileged and unprivileged work.
cwd (query)Starting directory of a new or reset local session; ignored on SSH. cwd_auto_create creates it.
displaySee Displays.
ssh_*, socks5_*See SSH sessions.
startup_scriptSee Startup script; cmd follows its own rule.

A session keeps its working directory, exported variables, shell history, background processes and open file descriptors. It ends on a delete, a computer restart, a terminal service restart, or idle cleanup: a session with no connected clients and no running process is removed after it has been idle for a while, and an idle ephemeral session is removed even if its process is stuck.

ResetDelete
Howreset=true on an execute call, or on the terminal URL opened in a browser. Fetching the page URL without opening it resets nothing.DELETE /api/v1/terminal/{terminal_id}
ShellEnded, and its process group signalled. A process that detached from that group keeps running.The same.
AfterwardsA fresh shell at once, for the page or request that reset it. Other attached tabs are disconnected; press Enter or click the reconnect message to attach again.The next request to that number creates a fresh session. Attached clients are closed with code 4410 and do not reconnect by themselves.
VariablesCleared.Gone.
DirectoryThe cwd you pass, else the service’s configured start directory, else the user’s home (/ if missing).
HistoryA fresh history buffer; history already written to the session’s history file stays.
Profile.bashrc or .zshrc runs again.
DisplayA display the session started keeps running. Stop it with POST /api/v1/system/displays/{display}/stop.
FieldRule
cwd (body)For a PTY command, changes to that directory before running the command and leaves the session there; the previous directory is not restored. On an SSH session, the directory is remote. On an SSH session, and on a session whose commands the service cannot stage as files, a failed change can still let later statements of the command run in the previous directory; guard directory-sensitive work inside command, as in cd /target && { make; make test; }. Pass it on every request that needs a directory, and keep directory-sensitive work on its own terminal. In raw mode, it sets the one-shot command’s working directory. The cwd query parameter of a new session is separate and ignored on SSH.
env (body)This command only. On an SSH session the variables stay exported in the remote shell, and so they do on a session whose commands the service cannot stage as files, such as one started as another user by a server not running as root.
mode: "raw"Runs the command outside the session, without a terminal, and returns exact bytes as stdout_b64 and stderr_b64, each up to a capture limit (check stdout_truncated and stderr_truncated). Requires wait: true.
idYour own numeric PTY command id; ignored in raw mode.

PTY command ids are 1 to 65535 (^[0-9]{1,5}$), and the result endpoint returns partial output while a PTY command runs. Raw mode answers when the command finishes; its command_id is a raw-N label that cannot be polled or aborted through the command endpoints.

PTY execution uses POSIX shell syntax. A local session running fish, another detected non-POSIX shell, or tmux returns 409 SHELL_UNSUPPORTED without running the command. Use write, press, paste and snapshot to drive tmux, or use a separate terminal with shell=bash or shell=sh. Raw mode runs in its own bash or sh process.

The command still runs, and the 200 reply has status and message instead of stdout, stderr and exit_code:

  • The session is an SSH session: wait: true is always forced off.
  • The request sets defer_pid: the command waits until that process exits.
  • 256 wait: true calls are already in flight across the service: the 257th is admitted but answered asynchronously.

Code that reads result.stdout there gets undefined.

statusMeaning
runningStarted, or with started: false waiting for an earlier command in the same session. It starts when that one finishes, unless it times out, is aborted, or, without a timeout, expires after 10 seconds of shell silence and never runs.
queuedHeld back by defer_pid, or waiting for an SSH session to become ready.
completed, timed_out, cancelledFinished.

A wait: false call can still be held up to 10 seconds while the session’s display starts, and behind an earlier request of the session that waits for it.

completionMeaning
markerFinished; exit_code is its real status.
timeoutThe timeout passed; exit code 124.
cancelledAborted.
endedThe session’s shell exited, or the command could not be delivered to it.
output_quietNo timeout and 10 seconds without output; exit_code is null and the command may still run.

started is false for a command that never began, for example one that timed out while waiting behind another.

In a terminal, the command’s own stderr arrives in stdout. stderr carries only diagnostics from the service, such as an SSH connection failure, and is otherwise empty. Lines usually end in \r\n, and leading and trailing whitespace is trimmed. To separate the streams, redirect inside the command (npm test 2>/tmp/err) and read the file, or use mode: "raw".

  • Persistent session: a timeout is a reporting deadline. When it passes, the command is recorded timed_out with exit_code: 124 and output capture stops, but no signal is sent: the process carries on in the shell, and later commands wait until it finishes.
  • Ephemeral session or mode: "raw": timeout cleanup sends SIGTERM, followed by SIGKILL 3 seconds later. Without a timeout, both use 600 seconds. A raw command run as another user through su, or through sudo with use_pty, can survive timeout or disconnect cleanup if it ignores SIGTERM, because it runs in a separate session.
  • Raw mode: the process group also receives SIGTERM, followed by SIGKILL after 3 seconds, if the HTTP client disconnects before the command finishes.
  • Abort: POST /api/v1/terminal/execute/{command_id}/abort sends Ctrl+C (SIGINT); {"force": true} kills the session’s process group, shell included. A command still waiting behind another is cancelled without running.
  • Abort after a timeout: works only if the command reached the same shell, that shell is still running, the command has not since reported completion, and no other input has reached that terminal. Input is any bytes: another command, keystrokes, write, press or paste, and also what an open browser sends by itself (focus reports, answers to terminal queries). Typing through a PID attachment into any terminal of the computer counts too; attaching and resizing alone do not. The result then shows status: "cancelled" with timed_out still true.
  • Otherwise abort answers 409 and sends nothing, since it can no longer tell what the signal would hit. Send Ctrl+C with the write endpoint instead.

Send "ephemeral": true to POST /api/v1/terminal/create on the terminal-0 hostname, without a terminal_id, and the service allocates an id from 5001 to 7999 that no session holds, and returns it. On a terminal-N hostname nothing is allocated: the session gets id N.

DifferenceDetail
No displayDISPLAY is stripped after the session is configured, even if the request set it, and no X display is started. A GUI program has nowhere to draw unless the session exports DISPLAY for a display that already exists. The stripping removes a default; it is not a sandbox.
Cleans itself upThe idle timeout is 60 seconds while it holds no command results, and --ephemeral-result-timeout (5 minutes by default) once it does, so a finished result stays fetchable that long. Past it, a session with no clients is destroyed, and a still-running process is killed.
Kills only its shellTeardown signals the shell, not the process group, so a process the session deliberately detached survives.

With no free id, create answers No available ephemeral terminal IDs (range 5001-7999 exhausted) rather than reusing one.

An executable /hoody/storage/hoody-terminal/scripts/startup.sh runs as the session’s user before the prompt when a local session’s shell starts through the browser, /create or a non-ephemeral /execute, and again after a reset. An ephemeral shell started by /execute skips the startup script. The file does not exist until you create it; make it executable with chmod +x.

  • A session’s display is set up by then. It normally starts when a program first uses it; a desktop session starts it at once, though it may not answer yet.
  • A failing script does not stop the session. A missing or non-executable default script is skipped silently; one chosen with startup_script prints a warning.
  • SSH sessions do not run it, and neither does a terminal owned by a daemon program.
  • It runs as its own process, so its cd or export does not reach the shell: put those in ~/.bashrc or ~/.zshrc, which also see TTYD_TERMINAL_ID. The prompt waits for it, so start long-running work in the background.
VariableValue
TTYD_TERMINAL_IDThe terminal id: 2 for terminal-2
HOODY_TERMINAL1 inside any Hoody terminal
DISPLAYThe terminal’s display (:2 for terminal 2), when it has one
DBUS_SESSION_BUS_ADDRESSThe display’s session bus, when one could be started
HOME, USERThe session user’s home directory and name
env given at creationAs given
The computer’s HOODY_* variablesSuch as HOODY_COMPUTER_ID and HOODY_COMPUTER_PROJECT_ID. Left out when the terminal is opened with env_inject=false; the create body cannot turn them off.
#!/bin/sh
# /hoody/storage/hoody-terminal/scripts/startup.sh
case "$TTYD_TERMINAL_ID" in
1) echo "terminal-1: main shell" ;;
2) # Start the dev server in the background, once per session
(cd /app && npm run dev >/tmp/dev-server.log 2>&1 &) ;;
esac

Another script for one session: pass startup_script on the URL or in the create body. It runs instead of the default. The path must be absolute and without ..: an invalid value on the URL is ignored, and in the create body it is refused with an error. It is chosen when the session is created, so reconnecting does not apply a new one. A reset keeps a script given this way, and a session on the default one can be given one on reset. To replace a given script, delete the session and create it again.

ShellLaunch
bashThe default, or ?shell=bash
zsh?shell=zsh, or exec zsh inside a session
fish?shell=fish, or exec fish
tmux?shell=tmux, or tmux inside a shell. To choose a name for SSH attachment, run tmux new-session -A -s N inside a shell, then use tmux attach -t N over SSH. /execute refuses a terminal whose shell is tmux (409 SHELL_UNSUPPORTED); drive it with write, press, paste and snapshot.
sh?shell=sh
ParameterEffect
reset=trueA fresh shell; add it when changing shell.
readonly=trueThis client can watch but not type.
title, fontSizeTab title, text size.
panel, panel-width, panel-positionA side panel showing another URL.
cwd, user, env, display, env_injectSession settings for a new session.
cmdA Base64 command. With no shell running, it becomes the session’s first command and runs once when the shell starts; the first connection that sets it wins. On a running shell, each writable connection’s cmd is typed into it, and a readonly=true connection ignores it. Give such a URL a terminal number of its own.
rendererType, rendererForceSee Renderers.

The web terminal runs in the native browsers on iOS and Android, with touch gestures (drag to scroll, long-press) and an on-screen keyboard, so you can administer a computer from a phone. Embed a terminal URL in an <iframe> for live command examples in docs, log dashboards or support portals; add readonly=true for a frame people can watch but not type into.

Switch with rendererType when characters draw as blocks, garbled or misplaced but look right in another browser. It works on agent-N URLs too.

ValueDraws with
webglThe GPU. Default in desktop browsers except Firefox.
domOrdinary page elements, independent of the GPU and its driver. Default in Firefox; slower when a program prints a lot very fast.
canvasAccepted; draws with WebGL.

Phones, tablets and other touch-screen devices use dom by default; add rendererType=webgl&rendererForce=webgl to try WebGL. The choice applies each time that URL connects and is not saved. If dom and webgl look the same, the program itself draws those cells: check its colours or theme.

  • display in the create body exports DISPLAY=:N into the shell. Matching numbers (terminal-2 with display: "2") is the usual convention.
  • On hostname-routed calls the proxy sets display from the same label as terminal_id, so a session first opened in a browser at terminal-5 gets DISPLAY=:5 and its windows land in display-5.
  • A session created with POST /api/v1/terminal/create reads display only from the body; without it there is no display. A ?display= query is overwritten by the hostname. You can also export DISPLAY inside the shell.
  • The first time a session for display N is created (CLI, SDK or URL), Hoody Terminal sets up :N if it is not running and display tooling is installed. A plain session leaves it waiting until a program connects, a viewer opens it or an API request acts on it. desktop: true or a desktop_env starts it at once. desktop: true shows the whole display as one screen and starts no window manager; desktop_env (xfce, mate) adds a desktop environment, which keeps running after the session is deleted.
  • Where the notifications plugin is present, the display’s notification service starts on demand too, so notifications to display N arrive once the session exists.
SettingMeaning
ssh_host, ssh_userThe remote host and account; both start an SSH session.
ssh_portDefault 22.
ssh_passwordPassword login. Percent-encode it in a URL.
ssh_keyThe base64 private key content, not a path. For a URL, encode it: base64 -w0 ~/.ssh/id_rsa | jq -sRr @uri.
socks5_hostA SOCKS5 proxy for a host the computer cannot route to. Setting it turns the proxy on.
socks5_portDefault 1080.
socks5_user, socks5_passOptional proxy credentials.
  • The settings are read only when a session starts. While it runs, different ones are ignored and commands run in that shell; reset=true closes the connection and connects again, to another server if you like.
  • The connection stays open until a reset or until the remote side closes it, so repeated commands are fast.
  • /api/v1/terminal/execute reads ssh_password and ssh_key from the query string, where they can land in URL logs. Put them, and the socks5_* fields, in the create body.
  • SOCKS5 becomes an SSH ProxyCommand running ncat --proxy-type socks5, with --proxy-auth when both credentials are set. A malformed host or a port outside 1 to 65535 fails session creation and names the value, rather than connecting directly.
  • Host keys are not checked (StrictHostKeyChecking=no), so unknown hosts are accepted.
  • A script in the computer can read a key from its files, such as /keys/.
  • Access to the terminal URL is controlled by proxy permissions, not by SSH keys.
  • For several servers in turn, send reset=true with each server’s settings and poll each command_id.

?panel=https://PROJECT_ID-COMPUTER_ID-agent-1.SERVER.computers.hoody.com&panel-width=40%&panel-position=left puts the Hoody Agent beside the terminal, in the same computer. Give each terminal its own agent (agent-1, agent-2) with its own profile. The URL holds the layout, so sharing it shares the terminal, agent, SSH connection and panel. Panel options are in the web interface API.

A daemon program with terminal_id: N runs in terminal N. Opening that terminal attaches to the program instead of starting a shell: you see its screen, type into it and detach while it keeps running.

  • The program follows the smallest writable client’s window size, or the smallest read-only one when none is writable.
  • Shell, working directory and command parameters are ignored there. Running a command answers 409 DAEMON_TERMINAL.
  • When the program is not running, the connection closes with code 4404.
  • hoody daemon programs terminal connect <program> and the SDK’s client.daemon.programs.connectTerminal find the terminal from the program.
  • hoody terminal sessions list shows every program terminal, opened or not, with daemon_program: true and the program’s id, name and state. A local shell already open on the id stays listed as that shell until deleted.

More in terminal programs.

RouteNotes
GET /api/v1/system/resourcesCPU, memory, uptime, per-interface network counters and per-disk I/O counters, not disk space. cpu.usage_percent covers the time since the previous call and is 0 on the first.
GET /api/v1/system/processessort (cpu, memory, pid, name), limit, filter (matched against the name or command line).
POST /api/v1/system/process/signal{"pid": 12345, "signal": "SIGTERM"} or {"name": "nginx", "signal": "SIGHUP"}; a name signals every matching process. force: true sends SIGKILL instead of signal; without it signal applies, SIGTERM by default.
POST /api/v1/system/processes/freeze, /unfreezeSuspend a process or process tree with SIGSTOP, and resume it.
GET /api/v1/system/daemonEach daemon program’s stored configuration, such as name, command, user, environment, enabled, boot and autorestart.
GET /api/v1/system/portsListening ports, filtered by protocol, user, port, ip, skip_program, http_only, hoody_only.
POST /api/v1/system/displays/{display}/stopStops the display and everything on it; answers { "display": 1, "stopped": true, "forced": false } once it is gone.
POST /api/v1/system/shutdown, /rebootShut down or reboot the computer.
POST /api/v1/terminal/stateOptional diagnostics beacon from the web client (build_id, renderer, reason, all optional), at most 4,096 bytes; a larger body is refused with 413.
  • Sessions: GET /api/v1/terminal/sessions lists each session with terminal_id, shell, cwd, created_at and recent command_history. Terminals of daemon programs that are not open yet appear with is_active: false.
  • History: GET /api/v1/terminal/history/{terminal_id} returns retained command records oldest first, with command_id, command, status, start_time, exit_code, completion, timed_out, cancelled and started, as the result endpoint gives them. exit_code is null while queued or running and with output_quiet; completion is null while queued or running.
  • History is a rolling window: initially 100 records by default. When full, the oldest finished record that no pending request still needs is dropped. If none can be dropped, the window expands and stays larger for that session. Pull it as you go for a complete record.
  • Output: GET /api/v1/terminal/raw exports the output the session still retains, up to 8 MB by default, dropping the oldest. format is download, text or html; tail keeps the last lines. It is no substitute for history.
  • Screenshot: GET /api/v1/terminal/screenshot renders the terminal screen as an image, for documentation, tutorials or monitoring dashboards. Choose format (png, jpeg, gif), colours (foreground, background) and fontsize. save (default true) also stores the image in /hoody/storage/hoody-terminal/screenshots/{terminal_id}/, named in the X-Screenshot-Path header. The hostname supplies terminal_id.
SymptomCauseFix
404 or a connection errorThe computer is not runningCheck data.status is running (and data.runtime_info.terminals) in GET https://api.hoody.com/api/v1/computers/{id}?runtime=true; start it with POST /api/v1/computers/{id}/start.
Web terminal will not loadComputer stopped, wrong URL (terminal-1, not terminal1), proxy permissions, or a browser blocking a cross-origin iframeStart the computer, fix the URL, check permissions, open the URL directly.
Request hangs on a long commandwait: true holds it openSend wait: false with a timeout, such as 600 for a large build, and poll.
exit_code: nulloutput_quiet: no timeout and 10 quiet secondsSend a non-zero timeout; past it the result is timeout with exit code 124.
exit_code: 0 despite an earlier failureThe shell command’s final status was zero, for example because a later command succeededCheck completion; with marker, the reported status is real. Use && between dependent commands, or propagate the failing command’s status explicitly. Error text may appear in stdout.
State not keptA different terminal-N, or the session endedSend every call to the same hostname; see session settings.
Remote SSH host unreachableSession already running (settings ignored), a firewall on the SSH port, wrong credentials, or no routeUse a fresh terminal or reset=true; test with ssh admin@host from the computer. On /execute the settings are query parameters.
409 DAEMON_TERMINALThe terminal belongs to a daemon programAttach instead; see daemon program terminals.