Terminal: Web UI & API Access

The terminal service exposes the browser-based shell experience and its machine-readable API description. The interactive web terminal HTML UI is served at the container root path and accepts an extensive set of URL parameters for configuring sessions, displays, SSH tunnels, side panels, and access control. Two additional endpoints serve the auto-generated OpenAPI 3.0 specification in JSON and YAML formats for tooling, client generation, and integration.

All endpoints live behind the per-container subdomain:

https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.icu

Web interface

`GET /`

The main web terminal interface that provides an interactive terminal in the browser. Supports extensive customization via URL parameters for session management, display settings, SSH connections, 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 a `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 an 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 a 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`).

curl -G "https://proj-abc123-cont-def456-terminal-1.us-east-1.containers.hoody.icu/" \
  --data-urlencode "title=Production Server" \
  --data-urlencode "fontSize=14" \
  --data-urlencode "shell=bash" \
  --data-urlencode "cwd=/home/user/projects" \
  --data-urlencode "backgroundColor=#1a1a1a"

import { HoodyClient } from "hoody-sdk";

const client = new HoodyClient({
  token: process.env.HOODY_TOKEN,
});

await client.terminal.web.get({
  title: "Production Server",
  fontSize: 14,
  shell: "bash",
  cwd: "/home/user/projects",
  backgroundColor: "#1a1a1a",
});

The web terminal interface HTML page.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>Hoody Terminal</title>
    <link rel="stylesheet" href="/xterm.css">
    <link rel="stylesheet" href="/hoody-terminal.css">
  </head>
  <body>
    <div id="terminal" data-terminal-id="41732"></div>
    <script src="/xterm.js"></script>
    <script src="/hoody-terminal.js"></script>
  </body>
</html>

OpenAPI specification

`GET /api/v1/terminal/openapi.json`

Retrieve the complete OpenAPI 3.0 specification for this API in JSON format. The specification is automatically generated from source code annotations.

This endpoint takes no parameters.

curl "https://proj-abc123-cont-def456-terminal-1.us-east-1.containers.hoody.icu/api/v1/terminal/openapi.json"

import { HoodyClient } from "hoody-sdk";

const client = new HoodyClient({
  token: process.env.HOODY_TOKEN,
});

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

{
  "openapi": "3.0.0",
  "info": {
    "title": "Hoody Terminal API",
    "version": "1.0.0",
    "description": "Auto-generated OpenAPI specification for the Hoody terminal service."
  },
  "servers": [
    {
      "url": "https://proj-abc123-cont-def456-terminal-1.us-east-1.containers.hoody.icu"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "summary": "Get web terminal interface",
        "responses": {
          "200": {
            "description": "Web terminal interface HTML page"
          }
        }
      }
    },
    "/api/v1/terminal/openapi.json": {
      "get": {
        "summary": "Get OpenAPI specification in JSON format"
      }
    },
    "/api/v1/terminal/openapi.yaml": {
      "get": {
        "summary": "Get OpenAPI specification in YAML format"
      }
    }
  }
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "OpenAPI specification file not found",
  "code": "SPEC_NOT_FOUND"
}

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

`GET /api/v1/terminal/openapi.yaml`

Retrieve the complete OpenAPI 3.0 specification for this API in YAML format. The specification is automatically generated from source code annotations.

This endpoint takes no parameters.

curl "https://proj-abc123-cont-def456-terminal-1.us-east-1.containers.hoody.icu/api/v1/terminal/openapi.yaml"

import { HoodyClient } from "hoody-sdk";

const client = new HoodyClient({
  token: process.env.HOODY_TOKEN,
});

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

openapi: 3.0.0
info:
  title: Hoody Terminal API
  version: 1.0.0
  description: Auto-generated OpenAPI specification for the Hoody terminal service.
servers:
  - url: https://proj-abc123-cont-def456-terminal-1.us-east-1.containers.hoody.icu
paths:
  /:
    get:
      summary: Get web terminal interface
      responses:
        '200':
          description: Web terminal interface HTML page
  /api/v1/terminal/openapi.json:
    get:
      summary: Get OpenAPI specification in JSON format
  /api/v1/terminal/openapi.yaml:
    get:
      summary: Get OpenAPI specification in YAML format

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "OpenAPI specification file not found",
  "code": "SPEC_NOT_FOUND"
}

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