Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

Terminal: Session Management

Section titled “Terminal: Session Management”

The Terminal Session API provides lifecycle management for in-container shell sessions. Use these endpoints to create persistent or ephemeral terminals, list active sessions, attach a WebSocket client for real-time bidirectional I/O, capture rendered screenshots, fetch raw output buffers, and tear sessions down cleanly.

All endpoints are served from the per-container terminal host https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com. Replace {projectId}, {containerId}, and {server} with the values from your deployment.

Sessions

Section titled “Sessions”

GET /api/v1/terminal/sessions

Section titled “GET /api/v1/terminal/sessions”

List all active terminal sessions. Each entry includes session metadata and a best-effort recent command history. Use history_limit to cap the number of history entries returned per session.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
history_limitqueryintegerNoMax command_history entries to include per session. Default: 50. Max: 1000.
history_linesqueryintegerNoAlias of history_limit.

Response

Section titled “Response”
[
  {
    "terminal_id": "1",
    "user": "alice",
    "shell": "bash",
    "cwd": "/home/alice",
    "created_at": "2026-01-15T12:00:00Z",
    "last_active_at": "2026-01-15T12:34:21Z",
    "command_history": [
      {
        "command": "ls -la",
        "executed_at": "2026-01-15T12:30:00Z",
        "status": "ok",
        "exit_code": 0
      },
      {
        "command": "git status",
        "executed_at": "2026-01-15T12:31:14Z",
        "status": "ok",
        "exit_code": 0
      }
    ]
  },
  {
    "terminal_id": "2",
    "user": "bob",
    "shell": "zsh",
    "cwd": "/var/www/app",
    "created_at": "2026-01-15T13:05:00Z",
    "last_active_at": "2026-01-15T13:10:42Z",
    "command_history": []
  }
]

SDK usage

Section titled “SDK usage”
import { HoodyClient } from 'hoody-sdk';


const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });


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

POST /api/v1/terminal/create

Section titled “POST /api/v1/terminal/create”

Create a new terminal session. Returns success if the session already exists. When a Hoody Display is configured, the request blocks until the display TCP port is accepting connections, so the caller can use the display immediately after the response returns.

This endpoint takes no parameters.

Request body

Section titled “Request body”
FieldTypeRequiredDescription
terminal_idstringNoTerminal session ID (numeric 1-65535). Required unless ephemeral is true, in which case it is auto-generated in the range 40000-65535. Example: "5".
ephemeralbooleanNoAuto-generate terminal ID and enable ephemeral session mode. Ephemeral sessions auto-clean after idle timeout and strip DISPLAY. Default: false.
displaystringNoX11 display number (for example "1" or ":1"). Sets the DISPLAY env var and enables Hoody Display readiness waiting.
shellstringNoShell to use (bash, zsh, fish, sh). Ignored for SSH sessions. Example: "bash".
userstringNoSystem user to spawn the shell as. Ignored for SSH sessions. Example: "user".
cwdstringNoWorking directory for the terminal. Ignored for SSH sessions. Example: "/home/user".
startup_scriptstringNoPath to a startup script to run. Example: "/path/to/init.sh".
welcomebooleanNoShow welcome message on startup. Default: false.
debugbooleanNoEnable debug output in wrapper script. Default: false.
desktopbooleanNoEnable Hoody Display desktop mode. Provides a full desktop environment instead of seamless individual windows. Default: false.
desktop_envstringNoDesktop environment to launch (implies desktop=true). Valid values: xfce, mate. Example: "xfce".
colsintegerNoTerminal columns. Default: 80.
rowsintegerNoTerminal rows. Default: 24.
wait_until_displaybooleanNoWhether to wait for Hoody Display readiness. Default: true when display is configured.
wait_timeoutintegerNoTimeout in seconds for waiting. Default: 300.
ssh_hoststringNoSSH hostname/IP. Required together with ssh_user for SSH sessions. Example: "192.168.1.100".
ssh_userstringNoSSH username. Required together with ssh_host for SSH sessions. Example: "admin".
ssh_portstringNoSSH port. Default: "22".
ssh_passwordstringNoSSH password. Cannot contain shell-dangerous characters.
ssh_keystringNoBase64-encoded SSH private key (PEM format).
socks5_hoststringNoSOCKS5 proxy hostname/IP for routing SSH connections.
socks5_portstringNoSOCKS5 proxy port. Default: "1080".
socks5_userstringNoSOCKS5 proxy authentication username.
socks5_passstringNoSOCKS5 proxy authentication password.
{
  "terminal_id": "5",
  "shell": "bash",
  "cwd": "/home/user",
  "cols": 100,
  "rows": 30,
  "welcome": true
}

Response

Section titled “Response”
{
  "terminal_id": "5",
  "status": "ready",
  "display": ":5",
  "ready": true
}

SDK usage

Section titled “SDK usage”
import { HoodyClient } from 'hoody-sdk';


const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });


await client.terminal.sessions.create({ terminal_id: '5', shell: 'bash', cwd: '/home/user', cols: 100, rows: 30 });

DELETE /api/v1/terminal/{terminal_id}

Section titled “DELETE /api/v1/terminal/{terminal_id}”

Destroy a terminal session. The running process is killed, all resources are released, and connected clients are disconnected. Use this to terminate sessions without waiting for idle timeout.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
terminal_idpathstringYesTerminal session ID to delete (numeric 1-65535).

Response

Section titled “Response”
{
  "terminal_id": "5",
  "deleted": true
}

SDK usage

Section titled “SDK usage”
import { HoodyClient } from 'hoody-sdk';


const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });


await client.terminal.sessions.delete(terminal_id);

WebSocket Connection

Section titled “WebSocket Connection”

GET /api/v1/terminal/ws

Section titled “GET /api/v1/terminal/ws”

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

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
terminal_idquerystringNoTerminal session ID (numeric 1-65535). Auto-generated if not provided. Multiple clients can share by using the same ID.
readonlybooleanNoEnable read-only mode for this client (blocks keyboard input). Use true, 1, or no value.
cwdquerystringNoWorking directory for new sessions.
cwd_auto_createbooleanNoAuto-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.
shellquerystringNoShell to use (bash, zsh, fish, tmux, ssh, etc.).
userquerystringNoSystem user to spawn shell as (requires permissions).
cmdquerystringNoBase64-encoded command to auto-execute on spawn.
envquerystringNoEnvironment variable in KEY=VALUE format (repeatable).
displayquerystringNoDISPLAY variable for X11 apps (auto-formats :N).
pidqueryintegerNoAttach to existing process PID for monitoring.
ssh_hostquerystringNoSSH server hostname/IP for remote connections.
ssh_userquerystringNoSSH username (required if ssh_host is provided).
ssh_portquerystringNoSSH port. Default: "22".
ssh_passwordquerystringNoSSH password (use with caution).
socks5_hostquerystringNoSOCKS5 proxy for SSH.
socks5_portquerystringNoSOCKS5 port. Default: "1080".

Response

Section titled “Response”
Switching Protocols

SDK usage

Section titled “SDK usage”
import { HoodyClient } from 'hoody-sdk';


const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });


await client.terminal.sessions.connectWebSocket({ terminal_id: '5', readonly: false, shell: 'bash' });

History and Output

Section titled “History and Output”

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

Section titled “GET /api/v1/terminal/history/{terminal_id}”

Retrieve the execution history for a specific terminal session, including every command and its status.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
terminal_idpathstringYesTerminal session ID (numeric 1-65535; can also be provided as a query parameter).

Response

Section titled “Response”
{
  "terminal_id": "5",
  "history": [
    {
      "command": "ls -la",
      "executed_at": "2026-01-15T12:00:01Z",
      "exit_code": 0,
      "status": "ok"
    },
    {
      "command": "npm install",
      "executed_at": "2026-01-15T12:01:42Z",
      "exit_code": 0,
      "status": "ok"
    },
    {
      "command": "exit",
      "executed_at": "2026-01-15T12:34:21Z",
      "exit_code": 0,
      "status": "ok"
    }
  ]
}

SDK usage

Section titled “SDK usage”
import { HoodyClient } from 'hoody-sdk';


const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });


await client.terminal.sessions.listHistoryIterator(terminal_id);

GET /api/v1/terminal/raw

Section titled “GET /api/v1/terminal/raw”

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

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
terminal_idquerystringNoTerminal session ID (numeric 1-65535). Default: "1".
formatquerystringNoOutput format. Allowed values: "download", "text", "html". Default: "download".
tailqueryintegerNoReturn only the last N lines of output.

Response

Section titled “Response”
$ ls -la
total 24
drwxr-xr-x 1 alice alice 4096 Jan 15 12:00 .
drwxr-xr-x 1 root  root  4096 Jan 15 11:30 ..
-rw-r--r-- 1 alice alice  220 Jan 15 11:30 .bash_logout
-rw-r--r-- 1 alice alice 3526 Jan 15 11:30 .bashrc
drwxr-xr-x 1 alice alice 4096 Jan 15 12:00 project
$ cd project

SDK usage

Section titled “SDK usage”
import { HoodyClient } from 'hoody-sdk';


const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });


await client.terminal.sessions.getRawOutput({ terminal_id: '5', format: 'text', tail: 200 });

Screenshots

Section titled “Screenshots”

GET /api/v1/terminal/screenshot

Section titled “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 timestamped filename.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
terminal_idquerystringYesTerminal session ID (numeric 1-65535).
formatquerystringNoOutput format. Allowed values: "png", "jpeg", "gif". Default: "png".
foregroundquerystringNoForeground color. Allowed values: black, red, green, yellow, blue, magenta, cyan, white, or R,G,B,A. Default: "white".
backgroundquerystringNoBackground color. Same options as foreground. Default: "black".
fontsizequeryintegerNoFont size in pixels. Default: 20.
savequerybooleanNoSave to the storage directory. Default: true.

Response

Section titled “Response”

Binary image data (content type image/gif for GIF, or image/png/image/jpeg depending on format). The response also includes an X-Screenshot-Path header indicating where the image was saved on disk, for example /hoody/storage/hoody-terminal/screenshots/5/2026-01-15T12-34-21Z.gif.

SDK usage

Section titled “SDK usage”
import { HoodyClient } from 'hoody-sdk';


const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });


await client.terminal.sessions.captureScreenshot({ terminal_id: '5', format: 'png', foreground: 'white', background: 'black', fontsize: 20, save: true });