The Terminal Web UI & API Access endpoints expose the browser-based interactive terminal and the machine-readable API specification. Use them to embed a customizable terminal session in a web client, or to programmatically retrieve the OpenAPI definition in JSON or YAML for tooling integration, client generation, or documentation.

Web Terminal Interface

GET /

Returns the interactive web terminal interface HTML page. The terminal can be heavily customized via URL query parameters controlling session sharing, display settings, SSH connections, proxying, and access control.

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
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-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 (requires --url-arg server option, 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)

Response

200

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Hoody Terminal</title>
  </head>
  <body>
    <div id="terminal"></div>
    <script src="/static/js/terminal.js"></script>
  </body>
</html>

SDK Usage

const terminal = await client.terminal.web.get({
  terminal_id: "42",
  shell: "bash",
  fontSize: 14,
  backgroundColor: "#1e1e1e",
  title: "Production Server",
  ssh_host: "10.0.0.5",
  ssh_user: "deploy",
  ssh_port: "2222",
});

---

OpenAPI Specification

GET /api/v1/terminal/openapi.json

Returns the complete OpenAPI 3.0 specification for this API in JSON format. The specification is automatically generated from source code annotations and is suitable for client generation, validation, and tooling integration.

This endpoint takes no parameters.

Response

200

{
  "openapi": "3.0.0",
  "info": {
    "title": "Hoody Terminal API",
    "version": "1.0.0"
  },
  "paths": {},
  "components": {}
}

404

{}

Error Code	Title	Description	Resolution
SPEC_NOT_FOUND	OpenAPI specification file missing	Regenerate spec with generate_openapi.py	Regenerate spec with generate_openapi.py

SDK Usage

const spec = await client.terminal.docs.getJson();

---

GET /api/v1/terminal/openapi.yaml

Returns the complete OpenAPI 3.0 specification for this API in YAML format. The specification is automatically generated from source code annotations and is suitable for human review, documentation tooling, and configuration of API gateways.

This endpoint takes no parameters.

Response

200

openapi: 3.0.0
info:
  title: Hoody Terminal API
  version: 1.0.0
paths: {}
components: {}

404

{}

Error Code	Title	Description	Resolution
SPEC_NOT_FOUND	OpenAPI specification file missing	Regenerate spec with generate_openapi.py	Regenerate spec with generate_openapi.py

SDK Usage

const specYaml = await client.terminal.docs.getYaml();