Terminals reference
Section titled “Terminals reference”Lookup tables for Hoody Terminal. Every route and field is in the API reference.
Session ids
Section titled “Session ids”- 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-5001addresses session 5001. - How many run at once depends on the computer’s resources.
- The hostname decides. On a
terminal-Nhostname, Hoody Proxy sets the queryterminal_idto N and overwrites any value you send. Only thePOST /api/v1/terminal/createbody field and{terminal_id}path parameters are yours, and they must name the host’s terminal.
Session settings
Section titled “Session settings”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.
| Setting | Notes |
|---|---|
shell | bash (default), zsh, fish, sh, or tmux in the browser. |
user | The 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. |
display | See Displays. |
ssh_*, socks5_* | See SSH sessions. |
startup_script | See 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.
Reset and delete
Section titled “Reset and delete”| Reset | Delete | |
|---|---|---|
| How | reset=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} |
| Shell | Ended, and its process group signalled. A process that detached from that group keeps running. | The same. |
| Afterwards | A 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. |
| Variables | Cleared. | Gone. |
| Directory | The cwd you pass, else the service’s configured start directory, else the user’s home (/ if missing). | |
| History | A fresh history buffer; history already written to the session’s history file stays. | |
| Profile | .bashrc or .zshrc runs again. | |
| Display | A display the session started keeps running. Stop it with POST /api/v1/system/displays/{display}/stop. |
Running commands
Section titled “Running commands”| Field | Rule |
|---|---|
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. |
id | Your 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.
When wait: true answers early
Section titled “When wait: true answers early”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: trueis always forced off. - The request sets
defer_pid: the command waits until that process exits. - 256
wait: truecalls are already in flight across the service: the 257th is admitted but answered asynchronously.
Code that reads result.stdout there gets undefined.
Status and completion
Section titled “Status and completion”status | Meaning |
|---|---|
running | Started, 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. |
queued | Held back by defer_pid, or waiting for an SSH session to become ready. |
completed, timed_out, cancelled | Finished. |
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.
completion | Meaning |
|---|---|
marker | Finished; exit_code is its real status. |
timeout | The timeout passed; exit code 124. |
cancelled | Aborted. |
ended | The session’s shell exited, or the command could not be delivered to it. |
output_quiet | No 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.
Output
Section titled “Output”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".
Timeouts and abort
Section titled “Timeouts and abort”- Persistent session: a
timeoutis a reporting deadline. When it passes, the command is recordedtimed_outwithexit_code: 124and 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 atimeout, both use 600 seconds. A raw command run as another user throughsu, or throughsudowithuse_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}/abortsends 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"withtimed_outstilltrue. - Otherwise abort answers
409and sends nothing, since it can no longer tell what the signal would hit. Send Ctrl+C with the write endpoint instead.
Ephemeral sessions
Section titled “Ephemeral sessions”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.
| Difference | Detail |
|---|---|
| No display | DISPLAY 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 up | The 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 shell | Teardown 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.
Startup script
Section titled “Startup script”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_scriptprints 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
cdorexportdoes not reach the shell: put those in~/.bashrcor~/.zshrc, which also seeTTYD_TERMINAL_ID. The prompt waits for it, so start long-running work in the background.
| Variable | Value |
|---|---|
TTYD_TERMINAL_ID | The terminal id: 2 for terminal-2 |
HOODY_TERMINAL | 1 inside any Hoody terminal |
DISPLAY | The terminal’s display (:2 for terminal 2), when it has one |
DBUS_SESSION_BUS_ADDRESS | The display’s session bus, when one could be started |
HOME, USER | The session user’s home directory and name |
env given at creation | As given |
The computer’s HOODY_* variables | Such 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.shcase "$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 &) ;;esacAnother 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.
Web terminal
Section titled “Web terminal”| Shell | Launch |
|---|---|
bash | The 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 |
| Parameter | Effect |
|---|---|
reset=true | A fresh shell; add it when changing shell. |
readonly=true | This client can watch but not type. |
title, fontSize | Tab title, text size. |
panel, panel-width, panel-position | A side panel showing another URL. |
cwd, user, env, display, env_inject | Session settings for a new session. |
cmd | A 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, rendererForce | See 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.
Renderers
Section titled “Renderers”Switch with rendererType when characters draw as blocks, garbled or misplaced but look right in another browser. It works on agent-N URLs too.
| Value | Draws with |
|---|---|
webgl | The GPU. Default in desktop browsers except Firefox. |
dom | Ordinary page elements, independent of the GPU and its driver. Default in Firefox; slower when a program prints a lot very fast. |
canvas | Accepted; 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.
Displays
Section titled “Displays”displayin the create body exportsDISPLAY=:Ninto the shell. Matching numbers (terminal-2withdisplay: "2") is the usual convention.- On hostname-routed calls the proxy sets
displayfrom the same label asterminal_id, so a session first opened in a browser atterminal-5getsDISPLAY=:5and its windows land indisplay-5. - A session created with
POST /api/v1/terminal/createreadsdisplayonly from the body; without it there is no display. A?display=query is overwritten by the hostname. You can also exportDISPLAYinside the shell. - The first time a session for display N is created (CLI, SDK or URL), Hoody Terminal sets up
:Nif 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: trueor adesktop_envstarts it at once.desktop: trueshows 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.
SSH sessions
Section titled “SSH sessions”| Setting | Meaning |
|---|---|
ssh_host, ssh_user | The remote host and account; both start an SSH session. |
ssh_port | Default 22. |
ssh_password | Password login. Percent-encode it in a URL. |
ssh_key | The base64 private key content, not a path. For a URL, encode it: base64 -w0 ~/.ssh/id_rsa | jq -sRr @uri. |
socks5_host | A SOCKS5 proxy for a host the computer cannot route to. Setting it turns the proxy on. |
socks5_port | Default 1080. |
socks5_user, socks5_pass | Optional 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=truecloses 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/executereadsssh_passwordandssh_keyfrom the query string, where they can land in URL logs. Put them, and thesocks5_*fields, in thecreatebody.- SOCKS5 becomes an SSH
ProxyCommandrunningncat --proxy-type socks5, with--proxy-authwhen 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=truewith each server’s settings and poll eachcommand_id.
Agent side panel
Section titled “Agent side panel”?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.
Daemon program terminals
Section titled “Daemon program terminals”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’sclient.daemon.programs.connectTerminalfind the terminal from the program.hoody terminal sessions listshows every program terminal, opened or not, withdaemon_program: trueand 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.
Monitoring
Section titled “Monitoring”| Route | Notes |
|---|---|
GET /api/v1/system/resources | CPU, 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/processes | sort (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, /unfreeze | Suspend a process or process tree with SIGSTOP, and resume it. |
GET /api/v1/system/daemon | Each daemon program’s stored configuration, such as name, command, user, environment, enabled, boot and autorestart. |
GET /api/v1/system/ports | Listening ports, filtered by protocol, user, port, ip, skip_program, http_only, hoody_only. |
POST /api/v1/system/displays/{display}/stop | Stops the display and everything on it; answers { "display": 1, "stopped": true, "forced": false } once it is gone. |
POST /api/v1/system/shutdown, /reboot | Shut down or reboot the computer. |
POST /api/v1/terminal/state | Optional diagnostics beacon from the web client (build_id, renderer, reason, all optional), at most 4,096 bytes; a larger body is refused with 413. |
History and output
Section titled “History and output”- Sessions:
GET /api/v1/terminal/sessionslists each session withterminal_id,shell,cwd,created_atand recentcommand_history. Terminals of daemon programs that are not open yet appear withis_active: false. - History:
GET /api/v1/terminal/history/{terminal_id}returns retained command records oldest first, withcommand_id,command,status,start_time,exit_code,completion,timed_out,cancelledandstarted, as the result endpoint gives them.exit_codeisnullwhile queued or running and withoutput_quiet;completionisnullwhile 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/rawexports the output the session still retains, up to 8 MB by default, dropping the oldest.formatisdownload,textorhtml;tailkeeps the last lines. It is no substitute for history. - Screenshot:
GET /api/v1/terminal/screenshotrenders the terminal screen as an image, for documentation, tutorials or monitoring dashboards. Chooseformat(png,jpeg,gif), colours (foreground,background) andfontsize.save(defaulttrue) also stores the image in/hoody/storage/hoody-terminal/screenshots/{terminal_id}/, named in theX-Screenshot-Pathheader. The hostname suppliesterminal_id.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause | Fix |
|---|---|---|
| 404 or a connection error | The computer is not running | Check 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 load | Computer stopped, wrong URL (terminal-1, not terminal1), proxy permissions, or a browser blocking a cross-origin iframe | Start the computer, fix the URL, check permissions, open the URL directly. |
| Request hangs on a long command | wait: true holds it open | Send wait: false with a timeout, such as 600 for a large build, and poll. |
exit_code: null | output_quiet: no timeout and 10 quiet seconds | Send a non-zero timeout; past it the result is timeout with exit code 124. |
exit_code: 0 despite an earlier failure | The shell command’s final status was zero, for example because a later command succeeded | Check 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 kept | A different terminal-N, or the session ended | Send every call to the same hostname; see session settings. |
| Remote SSH host unreachable | Session already running (settings ignored), a firewall on the SSH port, wrong credentials, or no route | Use a fresh terminal or reset=true; test with ssh admin@host from the computer. On /execute the settings are query parameters. |
409 DAEMON_TERMINAL | The terminal belongs to a daemon program | Attach instead; see daemon program terminals. |