The Terminal Session Management API exposes endpoints for inspecting, connecting to, and managing terminal sessions running inside a Hoody container. Use these endpoints to list active sessions, retrieve command history, capture screenshots of the ANSI buffer, establish WebSocket connections for real-time I/O, create new sessions (including SSH-backed and X11 display sessions), and tear sessions down explicitly when you are done with them.

All endpoints below are scoped to a specific container and are served from the container-scoped terminal subdomain.

Reading session state

GET /api/v1/terminal/history/{terminal_id}

Retrieve the execution history for a specific terminal session, including all commands executed and their status.

Parameters

Name	In	Type	Required	Description
terminal_id	path	string	Yes	Terminal session ID (numeric 1-65535, can also be provided as query parameter)

cURL

curl -G \
  "https://acme-prod-c1-terminal-1.eu.containers.hoody.icu/api/v1/terminal/history/42" \
  -H "Authorization: Bearer $HOODY_TOKEN"

SDK

await client.terminal.sessions.listHistoryIterator("42");

Response 200

{
  "terminal_id": "42",
  "history": [
    {
      "command": "ls -la",
      "executed_at": "2025-01-15T10:23:45Z",
      "exit_code": 0,
      "status": "success"
    },
    {
      "command": "cd /var/log",
      "executed_at": "2025-01-15T10:23:52Z",
      "exit_code": 0,
      "status": "success"
    }
  ]
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "terminal_id is required"
}

Error Code	Title	Description	Resolution
MISSING_TERMINAL_ID	Terminal ID required	Provide terminal_id in path or query	Provide terminal_id in path or query

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Session not found"
}

Error Code	Title	Description	Resolution
SESSION_NOT_FOUND	Terminal session does not exist	Check session ID or create new session	Check session ID or create new session

GET /api/v1/terminal/raw

Retrieve the raw terminal output buffer for a terminal session. Supports multiple output formats via the format query parameter. Defaults to text/download format if the format parameter is not provided.

Parameters

Name	In	Type	Required	Description
terminal_id	query	string	No	Terminal session ID (numeric 1-65535, defaults to "1" if not provided)
format	query	string	No	Output format: download, text, or html (defaults to "download" if not provided)
tail	query	integer	No	Return only the last N lines of output

cURL

curl -G \
  "https://acme-prod-c1-terminal-1.eu.containers.hoody.icu/api/v1/terminal/raw" \
  --data-urlencode "terminal_id=42" \
  --data-urlencode "format=text" \
  --data-urlencode "tail=100" \
  -H "Authorization: Bearer $HOODY_TOKEN"

SDK

await client.terminal.sessions.getRawOutput({
  terminal_id: "42",
  format: "text",
  tail: 100
});

Response 200

{
  "statusCode": 200,
  "contentType": "application/octet-stream"
}

The body is returned as a downloadable text file (when format=download, format=text, or no format is specified).

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Session not found"
}

GET /api/v1/terminal/screenshot

Convert the terminal’s ANSI output buffer to an image with customizable styling. Screenshots are automatically saved to /hoody/storage/hoody-terminal/screenshots/{terminal_id}/ with a timestamp as filename.

Parameters

Name	In	Type	Required	Description
terminal_id	query	string	Yes	Terminal session ID (numeric 1-65535)
format	query	string	No	Output format: png, jpeg, gif (default: png)
foreground	query	string	No	Foreground color: black, red, green, yellow, blue, magenta, cyan, white, or RGB R,G,B,A (default: white)
background	query	string	No	Background color: same as foreground options (default: black)
fontsize	query	integer	No	Font size in pixels (default: 20)
save	query	boolean	No	Save to storage directory (default: true)

cURL

curl -G \
  "https://acme-prod-c1-terminal-1.eu.containers.hoody.icu/api/v1/terminal/screenshot" \
  --data-urlencode "terminal_id=42" \
  --data-urlencode "format=png" \
  --data-urlencode "foreground=white" \
  --data-urlencode "background=black" \
  --data-urlencode "fontsize=18" \
  --data-urlencode "save=true" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -o screenshot.png

SDK

await client.terminal.sessions.captureScreenshot({
  terminal_id: "42",
  format: "png",
  foreground: "white",
  background: "black",
  fontsize: 18,
  save: true
});

Response 200

{
  "statusCode": 200,
  "headers": {
    "Content-Type": "image/gif",
    "X-Screenshot-Path": "/hoody/storage/hoody-terminal/screenshots/42/2025-01-15T10-25-31Z.gif"
  }
}

The body is the binary image content.

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Screenshot tool not available"
}

Error Code	Title	Description	Resolution
TOOL_NOT_AVAILABLE	Screenshot tool (textimg) not installed	Install with: go install github.com/jiro4989/textimg@latest	Install with: go install github.com/jiro4989/textimg@latest

Session lifecycle

GET /api/v1/terminal/sessions

Returns a JSON array of all active terminal sessions with session metadata and recent command history (best-effort).

Parameters

Name	In	Type	Required	Description
history_limit	query	integer	No	Max command_history entries to include per session (default: 50, max: 1000)
history_lines	query	integer	No	Alias of history_limit

cURL

curl -G \
  "https://acme-prod-c1-terminal-1.eu.containers.hoody.icu/api/v1/terminal/sessions" \
  --data-urlencode "history_limit=20" \
  -H "Authorization: Bearer $HOODY_TOKEN"

SDK

await client.terminal.sessions.listIterator({ history_limit: 20 });

Response 200

{
  "sessions": [
    {
      "terminal_id": "1",
      "shell": "bash",
      "user": "root",
      "cwd": "/root",
      "created_at": "2025-01-15T08:12:04Z",
      "last_activity_at": "2025-01-15T10:24:51Z",
      "client_count": 1,
      "command_history": [
        "ls -la",
        "cd /var/log",
        "tail -n 100 syslog"
      ]
    },
    {
      "terminal_id": "5",
      "shell": "zsh",
      "user": "deploy",
      "cwd": "/home/deploy/app",
      "created_at": "2025-01-15T09:01:18Z",
      "last_activity_at": "2025-01-15T10:18:02Z",
      "client_count": 2,
      "command_history": [
        "git status",
        "git pull --rebase"
      ]
    }
  ]
}

POST /api/v1/terminal/create

Create a new terminal session, or return success if it already exists. By default, when a Hoody Display is configured, the endpoint blocks until the display TCP port (4000 + display_number) is accepting connections. This ensures the caller can immediately use the display after the response.

Request Body

Field	Type	Required	Description
terminal_id	string	No	Terminal session ID (numeric 1-65535). Required unless ephemeral is true, in which case it is auto-generated (range 40000-65535). Example: "5"
ephemeral	boolean	No	Auto-generate terminal ID and enable ephemeral session mode. Ephemeral sessions auto-clean after idle timeout and strip DISPLAY environment. (default: false)
display	string	No	X11 display number (e.g., "1" or ":1"). Sets the DISPLAY env var and enables Hoody Display readiness waiting. Example: "5"
shell	string	No	Shell to use (bash/zsh/fish/sh). Ignored for SSH sessions. Example: "bash"
user	string	No	System user to spawn the shell as. Ignored for SSH sessions. Example: "user"
cwd	string	No	Working directory for the terminal. Ignored for SSH sessions. Example: "/home/user"
startup_script	string	No	Path to startup script to run. Example: "/path/to/init.sh"
welcome	boolean	No	Show welcome message on startup (default: false)
debug	boolean	No	Enable debug output in wrapper script (default: false)
desktop	boolean	No	Enable Hoody Display desktop mode. Provides a full desktop environment instead of seamless individual windows (default: false)
desktop_env	string	No	Desktop environment to launch (implies desktop=true). Valid values: xfce, mate. Example: "xfce"
cols	integer	No	Terminal columns (default: 80). Example: 80
rows	integer	No	Terminal rows (default: 24). Example: 24
wait_until_display	boolean	No	Whether to wait for Hoody Display readiness (default: true when display is configured).
wait_timeout	integer	No	Timeout in seconds for waiting (default: 300). Example: 300
ssh_host	string	No	SSH hostname/IP. Required together with ssh_user for SSH sessions. Example: "192.168.1.100"
ssh_user	string	No	SSH username. Required together with ssh_host for SSH sessions. Example: "admin"
ssh_port	string	No	SSH port (default: 22). Example: "22"
ssh_password	string	No	SSH password. Cannot contain shell-dangerous characters.
ssh_key	string	No	Base64-encoded SSH private key (PEM format)
socks5_host	string	No	SOCKS5 proxy hostname/IP for routing SSH connections
socks5_port	string	No	SOCKS5 proxy port (default: 1080)
socks5_user	string	No	SOCKS5 proxy authentication username
socks5_pass	string	No	SOCKS5 proxy authentication password

cURL

curl -X POST \
  "https://acme-prod-c1-terminal-1.eu.containers.hoody.icu/api/v1/terminal/create" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "terminal_id": "5",
    "display": "5",
    "shell": "bash",
    "user": "deploy",
    "cwd": "/home/deploy/app",
    "cols": 120,
    "rows": 32,
    "welcome": true
  }'

SDK

await client.terminal.sessions.create({
  terminal_id: "5",
  display: "5",
  shell: "bash",
  user: "deploy",
  cwd: "/home/deploy/app",
  cols: 120,
  rows: 32,
  welcome: true
});

Response 200

{
  "status": "ok",
  "terminal_id": "5",
  "created": true,
  "display_ready": true,
  "pid": 4123
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid terminal_id"
}

Error Code	Title	Description	Resolution
MISSING_TERMINAL_ID	terminal_id field is required	terminal_id field is required	Contact support
INVALID_TERMINAL_ID	Terminal ID must be numeric 1-65535	Terminal ID must be numeric 1-65535	Contact support

403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "CWD cannot be created"
}

Error Code	Title	Description	Resolution
CWD_PERMISSION_DENIED	Requested working directory could not be created	Choose a writable path or disable cwd_auto_create	Choose a writable path or disable cwd_auto_create

405

{
  "statusCode": 405,
  "error": "Method Not Allowed",
  "message": "Use POST to create sessions",
  "headers": {
    "Allow": "POST",
    "Connection": "close"
  }
}

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to spawn terminal process"
}

Error Code	Title	Description	Resolution
SPAWN_FAILED	Failed to create terminal process	Failed to create terminal process	Contact support

DELETE /api/v1/terminal/{terminal_id}

Completely destroy and remove a terminal session. This kills any running process, frees all resources, and removes the session from memory. Clients will be disconnected. Use this to cleanly terminate sessions without waiting for idle timeout.

Parameters

Name	In	Type	Required	Description
terminal_id	path	string	Yes	Terminal session ID to delete (numeric 1-65535)

cURL

curl -X DELETE \
  "https://acme-prod-c1-terminal-1.eu.containers.hoody.icu/api/v1/terminal/42" \
  -H "Authorization: Bearer $HOODY_TOKEN"

SDK

await client.terminal.sessions.delete("42");

Response 200

{
  "status": "ok",
  "terminal_id": "42",
  "deleted": true
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Session not found"
}

Error Code	Title	Description	Resolution
SESSION_NOT_FOUND	Terminal session does not exist	Verify terminal ID	Verify terminal ID

Real-time I/O

GET /api/v1/terminal/ws

Establishes a WebSocket connection for real-time bidirectional terminal I/O. Multiple clients can share the same terminal session using the same terminal_id. The protocol uses efficient binary framing where the first byte indicates message type (0-4 for commands, specific bytes for data). Supports session sharing, read-only mode, SSH connections, PID attachment, and comprehensive terminal features.

Parameters

Name	In	Type	Required	Description
terminal_id	query	string	No	Terminal session ID (numeric 1-65535, auto-generated if not provided). Multiple clients can share by using same ID
readonly	query	boolean	No	Enable read-only mode for this client (blocks keyboard input). Use true, 1, or no value
cwd	query	string	No	Working directory for new sessions
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 local session. Enable with true, 1, or no value (default: false)
shell	query	string	No	Shell to use (bash, zsh, fish, tmux, ssh, etc.)
user	query	string	No	System user to spawn shell as (requires permissions)
cmd	query	string	No	Base64-encoded command to auto-execute on spawn
env	query	string	No	Environment variable KEY=VALUE (repeatable)
display	query	string	No	DISPLAY variable for X11 apps (auto-formats N)
pid	query	integer	No	Attach to existing process PID for monitoring
ssh_host	query	string	No	SSH server hostname/IP for remote connections
ssh_user	query	string	No	SSH username (required if ssh_host provided)
ssh_port	query	string	No	SSH port (default: 22)
ssh_password	query	string	No	SSH password (use with caution)
socks5_host	query	string	No	SOCKS5 proxy for SSH
socks5_port	query	string	No	SOCKS5 port (default: 1080)

cURL

curl -G \
  --include \
  --no-buffer \
  --header "Connection: Upgrade" \
  --header "Upgrade: websocket" \
  --header "Sec-WebSocket-Version: 13" \
  --header "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
  "https://acme-prod-c1-terminal-1.eu.containers.hoody.icu/api/v1/terminal/ws" \
  --data-urlencode "terminal_id=42" \
  --data-urlencode "shell=bash" \
  --data-urlencode "cwd=/home/deploy/app"

SDK

await client.terminal.sessions.connectWebSocket({
  terminal_id: "42",
  shell: "bash",
  cwd: "/home/deploy/app"
});

Response 101

{
  "statusCode": 101,
  "status": "Switching Protocols",
  "headers": {
    "Upgrade": "websocket",
    "Connection": "Upgrade"
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid parameters"
}

Error Code	Title	Description	Resolution
INVALID_TERMINAL_ID	Terminal ID must be numeric 1-65535	Provide valid terminal_id	Provide valid terminal_id
INVALID_PARAMETERS	Invalid URL parameters	Check parameter format	Check parameter format

403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Cannot connect"
}

Error Code	Title	Description	Resolution
MAX_CLIENTS_REACHED	Server at capacity	Try again later	Try again later
ORIGIN_CHECK_FAILED	Origin validation failed	Connect from allowed origin	Connect from allowed origin

503

{
  "statusCode": 503,
  "error": "Service Unavailable",
  "message": "Terminal service unavailable"
}