Terminal: Web Interface

The web terminal interface provides an interactive browser-based terminal session hosted inside a container. This endpoint serves the HTML page that loads the terminal client and connects to a backend shell session. Most behavior is controlled through URL query parameters, allowing deep-linking to specific sessions, shells, SSH connections, side panels, and desktop environments without changing the endpoint itself.

Note

This endpoint returns an HTML page rather than JSON, so the SDK has no method that fetches it. client.embeds.terminal.session(container, { index, params }) builds its URL instead, for a browser tab or a frame; see Embed a kit UI. The builder takes the HTTP query names as they are ('panel-position', not panelPosition) and refuses the parameters that start a process or carry a credential (shell, ssh_*, desktop_env, display and others): put those in the URL yourself. The cURL examples show how the query parameters compose into a shareable URL.

Get web terminal interface

GET /

Loads the web terminal interface HTML page. The query parameters on this request configure the session, display, and optional side panel that the page will render.

Parameters

Name	In	Type	Required	Description
terminal_id	query	string	No	Terminal session ID (numeric 1-65535, auto-generated if not provided). Allows multiple clients to share the same terminal session. On calls routed through a terminal-N containers-proxy hostname, the proxy sets this from the hostname label and overwrites any value you send
cwd	query	string	No	Initial working directory for new terminal sessions (only applied when session is first created)
cwd_auto_create	query	boolean	No	Auto-create cwd when the requested working directory does not exist yet. Only applies when cwd is explicitly provided for a new session. Enable with true, 1, or no value (default: false)
shell	query	string	No	Shell to use: bash, zsh, fish, sh, etc. (default: server startup command, only applies to new sessions)
user	query	string	No	System user to spawn shell as (requires su permissions, only applies to new sessions, user must exist on system)
cmd	query	string	No	Base64-encoded command to execute automatically on spawn (executes once when shell starts)
readonly	query	boolean	No	Enable read-only mode (blocks keyboard input, allows viewing only). Use true, 1, or no value
title	query	string	No	Browser window/tab title (default: application default). HTML tags removed, max 200 characters, useful for organizing multiple terminal tabs
fontSize	query	integer	No	Terminal font size in pixels (default: 13, range: 8 to 72). Accepts px suffix (e.g., 16px), applied immediately when terminal loads
backgroundColor	query	string	No	Terminal background color (default: #2b2b2b). Supports hex colors (#RGB, #RRGGBB, #RRGGBBAA) or CSS named colors (black, white, red, blue, green, navy, etc.)
panel	query	string	No	URL to display in side panel iframe (enables panel feature)
panel-visible	query	boolean	No	Show panel on load (default: true if panel URL provided, false otherwise)
panel-position	query	string	No	Panel position: left or right (default: right)
panel-width	query	string	No	Initial panel width in pixels or percentage (default: 400px)
panel-resizable	query	boolean	No	Allow panel resizing via drag handle (default: true)
hide-toolbar	query	boolean	No	Hide the terminal toolbar (default: false)
ssh_host	query	string	No	SSH server hostname or IP address (creates SSH session if provided with ssh_user)
ssh_user	query	string	No	SSH username (required if ssh_host is provided)
ssh_port	query	string	No	SSH port number (default: 22)
ssh_password	query	string	No	SSH password for authentication (use with caution, prefer key-based auth)
socks5_host	query	string	No	SOCKS5 proxy hostname for SSH connection
socks5_port	query	string	No	SOCKS5 proxy port (default: 1080)
socks5_user	query	string	No	SOCKS5 proxy username for authentication
socks5_pass	query	string	No	SOCKS5 proxy password for authentication
desktop	query	boolean	No	Enable Hoody Display desktop mode. Provides a full desktop environment instead of seamless individual windows (default: false)
desktop_env	query	string	No	Desktop environment to launch (implies desktop=true). Starts the specified DE session after the display is ready. Valid values: xfce, mate
redirect	query	string	No	Redirect mode. When set to display, creates/ensures the terminal session, waits for X11 display readiness, then returns HTTP 302 redirect to the display URL. Requires terminal_id and display params
redirect_delay	query	integer	No	Extra delay in seconds after display is ready before redirecting. Only used when redirect=display (default: 0)
arg	query	string	No	Command-line arguments to pass to shell; accepted only where the deployment enabled shell arguments, and can be repeated
welcome	query	boolean	No	Show welcome message on startup (default: false). Supports ?welcome=true, ?welcome=1, or ?welcome (no value = true)
debug	query	boolean	No	Enable debug output in wrapper script (default: false)
reset	query	boolean	No	Kill existing terminal process and reconfigure session (default: false). Use to switch shell, user, or from shell to SSH
pid	query	integer	No	Attach to an existing process by PID instead of spawning a new shell. Implies reset
env	query	string	No	Inject environment variable as KEY=VALUE. Can be repeated for multiple variables (e.g., ?env=FOO=bar&env=BAZ=qux)
display	query	string	No	X11 display number for GUI applications. Accepts number (e.g., 1) or :number (e.g., :1). Shorthand for ?env=DISPLAY=:N
env_inject	query	boolean	No	Inject HOODY_* environment variables into shell session (default: true). Set to false to disable
startup_script	query	string	No	Path to startup script to execute before shell launch (only applied on first session creation)
ssh_key	query	string	No	Base64-encoded SSH private key for key-based authentication (prefer over password-based auth)
panel-height	query	string	No	Initial panel height for top/bottom positioned panels (default: 300px)
panel-width-pct	query	integer	No	Initial panel width as a percentage of the window, 5-95. Takes precedence over panel-width
panel-height-pct	query	integer	No	Initial panel height as a percentage of the window for top/bottom panels, 5-95. Takes precedence over panel-height
wait_timeout	query	integer	No	Seconds to wait for the display to become ready before redirecting (default: 60, capped at 300). Only used when redirect=display
rendererType	query	string	No	Terminal renderer: dom, canvas or webgl (default: webgl, or dom in Firefox)
fontFamily	query	string	No	Terminal font family, as a CSS font-family list
fontWeight	query	string	No	Font weight of normal text: normal, bold, or 100 to 900
fontWeightBold	query	string	No	Font weight of bold text: normal, bold, or 100 to 900
lineHeight	query	integer	No	Line height as a multiple of the font size (read as a whole number)
letterSpacing	query	integer	No	Extra space between characters, in whole pixels
cursorBlink	query	boolean	No	Blink the cursor. Use ‘true’ or ‘1’
cursorStyle	query	string	No	Cursor shape: block, underline or bar
cursorWidth	query	integer	No	Width of the bar cursor in pixels
cursorInactiveStyle	query	string	No	Cursor shape while the terminal is not focused: outline, block, bar, underline or none
theme	query	string	No	Color theme as a JSON object of xterm theme keys, e.g. {“background”:“#000000”,“foreground”:“#ffffff”}
minimumContrastRatio	query	integer	No	Minimum contrast ratio between text and background, 1 (no adjustment) to 21
drawBoldTextInBrightColors	query	boolean	No	Draw bold text in the bright ANSI colors. Use ‘true’ or ‘1’
scrollback	query	integer	No	Number of lines kept in the scrollback buffer
scrollSensitivity	query	integer	No	Scroll speed multiplier
fastScrollSensitivity	query	integer	No	Scroll speed multiplier while the fast-scroll modifier key is held
smoothScrollDuration	query	integer	No	Smooth scrolling duration in milliseconds (0 turns it off)
screenReaderMode	query	boolean	No	Turn on screen reader support. Use ‘true’ or ‘1’
disableResizeOverlay	query	boolean	No	Hide the size overlay shown while the terminal is resized. Use ‘true’ or ‘1’
unicodeVersion	query	string	No	Character width tables: graphemes (default) or 11

Request

This endpoint accepts no request body.

Response

200

The 200 response is the text/html terminal page that loads the client and connects to the configured session. Open it in a browser to start the session.

409

Returned when redirect=display is used with a terminal id that belongs to a hoody-daemon program. The terminal runs the program, so no session or display is started there.

{
  "error": "terminal 7000 belongs to a daemon program and has no shell; drive it with snapshot/press/paste/write/wait or attach over WebSocket",
  "code": "DAEMON_TERMINAL"
}

Error Code	Title	Description	Resolution
DAEMON_TERMINAL	Terminal belongs to a daemon program	The terminal id belongs to a hoody-daemon program, so no shell or display is started	Open the terminal without redirect=display to watch the program

SDK and cURL

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const hoody = await HoodyClient.login('https://api.hoody.com', { username, password });
const box = await hoody.withContainer(containerId);

// Builds the URL of terminal session 1042; nothing is fetched.
const url = box.embeds.terminal.session(undefined, {
  index: 1042,
  params: { title: 'Production logs', fontSize: 14, backgroundColor: '#1e1e2e', cwd: '/var/log' },
});

The builder refuses shell: add shell=bash to the URL yourself, as in the cURL tab.

cURL

curl -G "https://{projectId}-{containerId}-terminal-1042.{server}.containers.hoody.com/" \
  --data-urlencode "shell=bash" \
  --data-urlencode "title=Production logs" \
  --data-urlencode "fontSize=14" \
  --data-urlencode "backgroundColor=#1e1e2e" \
  --data-urlencode "cwd=/var/log"

Example: shared session with side panel

The panel parameter opens a side iframe for context (docs, dashboards, logs). Other browser tabs that use the same terminal-N host label attach to the same session.

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const hoody = await HoodyClient.login('https://api.hoody.com', { username, password });
const box = await hoody.withContainer(containerId);

// Builds the URL of terminal session 1042 with a side panel; nothing is fetched.
const url = box.embeds.terminal.session(undefined, {
  index: 1042,
  params: { panel: 'https://docs.example.com/runbook', 'panel-position': 'right', 'panel-width': '420px' },
});

cURL

curl -G "https://{projectId}-{containerId}-terminal-1042.{server}.containers.hoody.com/" \
  --data-urlencode "panel=https://docs.example.com/runbook" \
  --data-urlencode "panel-position=right" \
  --data-urlencode "panel-width=420px"

Example: SSH session with key authentication

When ssh_host and ssh_user are provided, the session connects through SSH instead of spawning a local shell. Prefer ssh_key over ssh_password.

TypeScript SDK

The SDK has no call for this example: client.embeds.terminal.session() refuses the ssh_* parameters because they carry a credential. Build the URL yourself, as in the cURL tab.

cURL

curl -G "https://{projectId}-{containerId}-terminal-2049.{server}.containers.hoody.com/" \
  --data-urlencode "ssh_host=10.0.0.12" \
  --data-urlencode "ssh_user=ops" \
  --data-urlencode "ssh_port=2222" \
  --data-urlencode "ssh_key=LS0tLS1CRUdJTi...base64-encoded-private-key..."

Example: desktop environment launch

Set desktop_env to launch a full desktop environment (implies desktop=true). The browser becomes a remote desktop client.

TypeScript SDK

The SDK has no call for this example: client.embeds.terminal.session() refuses desktop_env and display. Build the URL yourself, as in the cURL tab.

cURL

curl -G "https://{projectId}-{containerId}-terminal-1042.{server}.containers.hoody.com/" \
  --data-urlencode "desktop_env=xfce" \
  --data-urlencode "display=:1"

Caution

When routed via a terminal-N containers-proxy hostname, the proxy sets terminal_id from the hostname label and overwrites any value you send. Address the session through the host label and omit terminal_id from the query string; it only applies when calling the service without the proxy.