# Terminals reference **Page:** kit/terminals/reference [Download Raw Markdown](./kit/terminals/reference.md) --- # Terminals reference Lookup tables for [Hoody Terminal](/kit/terminals/). Every route and field is in the [API reference](/api/terminal/). ## 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-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. ## 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](#displays). | | `ssh_*`, `socks5_*` | See [SSH sessions](#ssh-sessions). | | `startup_script` | See [Startup script](#startup-script); `cmd` follows [its own rule](#web-terminal). | 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 | | 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 | 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 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`. ### 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 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 - **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. ## 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 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. | 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. | ```bash #!/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. ## 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](#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 `