Terminal: Web UI & API Access

Web Terminal Interface

The web terminal interface provides an interactive, browser-based terminal that supports extensive customization via URL parameters. This section covers the main entry point and the OpenAPI specification endpoints used for programmatic API access and integration.

Get web terminal interface

GET /

Returns the main web terminal interface HTML page. The endpoint supports session management, display customization, SSH connectivity, panel integration, and access control through query parameters.

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`.
`panel-height`	query	string	No	Initial panel height for top/bottom positioned panels. Default: `300px`.
`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).
`ssh_key`	query	string	No	Base64-encoded SSH private key for key-based authentication (prefer over password-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).

Response

Returns the web terminal interface HTML page (text/html).

{
  "description": "Web terminal interface HTML page",
  "content": {
    "text/html": {
      "schema": {
        "type": "object"
      }
    }
  }
}

SDK usage

const html = await client.terminal.web.get({
  terminal_id: "42",
  shell: "bash",
  fontSize: 14,
  backgroundColor: "#1e1e1e",
  title: "Production Server",
  panel: "https://example.com/sidebar",
  panel-position: "right",
  panel-width: "350px",
  welcome: true
});

curl -X GET "https://api.example.com/?terminal_id=42&shell=bash&fontSize=14&backgroundColor=%231e1e1e&title=Production%20Server&welcome=true" \
  -H "Authorization: Bearer <token>"

OpenAPI Specification

The API exposes its own OpenAPI 3.0 specification in both JSON and YAML formats. The spec is auto-generated from source code annotations and can be used to bootstrap client SDKs, generate documentation, or validate integrations.

Get OpenAPI specification in JSON format

GET /api/v1/terminal/openapi.json

Retrieve the complete OpenAPI 3.0 specification in JSON format.

This endpoint takes no parameters.

Response

Returns the OpenAPI 3.0 specification as JSON.

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

Specification file was not found on the server.

{}

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();
console.log(spec.openapi, spec.info.version);

curl -X GET "https://api.example.com/api/v1/terminal/openapi.json" \
  -H "Authorization: Bearer <token>"

Get OpenAPI specification in YAML format

GET /api/v1/terminal/openapi.yaml

Retrieve the complete OpenAPI 3.0 specification in YAML format.

This endpoint takes no parameters.

Response

Returns the OpenAPI 3.0 specification as YAML.

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

Specification file was not found on the server.

{}

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 yamlSpec = await client.terminal.docs.getYaml();

curl -X GET "https://api.example.com/api/v1/terminal/openapi.yaml" \
  -H "Authorization: Bearer <token>"