Terminal: Web UI & API Access

The terminal service exposes a browser-based interactive terminal and serves its own machine-readable API specification. Use these endpoints to embed or link to the web terminal UI in your tooling and to fetch the OpenAPI definition that documents the terminal’s HTTP surface.

All endpoints in this section are served from a container-scoped hostname. The placeholder {server} is the regional node label assigned to your container (for example, node-us).

Web Terminal Interface

`GET /`

Returns the HTML page for the interactive browser terminal. Every aspect of the session — shell, working directory, appearance, SSH target, side panel, display mode — is controlled through URL query parameters. Most parameters only take effect the first time a terminal_id is seen; subsequent requests with the same terminal_id reattach to the existing process unless reset=true.

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.
`fontSize`	query	integer	No	Terminal font size in pixels. Default: `13`, range: `8`-`72`. Accepts a `px` suffix (e.g. `16px`).
`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 a `panel` URL is 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`.
`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`.
`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 means `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`).
`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

The HTML document for the browser-based terminal. The page boots the terminal WebSocket client and applies the supplied query parameters.

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

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.web.get({
  terminal_id: '1',
  shell: 'bash',
  cwd: '/workspace',
  fontSize: 14,
  backgroundColor: '#1e1e1e',
  title: 'My Terminal',
  hide_toolbar: false
});

curl -G \
  --data-urlencode "terminal_id=1" \
  --data-urlencode "shell=bash" \
  --data-urlencode "cwd=/workspace" \
  --data-urlencode "fontSize=14" \
  --data-urlencode "backgroundColor=#1e1e1e" \
  --data-urlencode "title=My Terminal" \
  "https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com/"

API Documentation

These endpoints expose the terminal’s own OpenAPI specification, generated from the service’s source annotations. Use them when you need to generate client code, render docs, or validate requests against the live schema.

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

Returns the full OpenAPI 3.0 specification for the terminal service as JSON.

Response

{
  "openapi": "3.0.0",
  "info": {
    "title": "Hoody Terminal API",
    "version": "1.0.0",
    "description": "HTTP API for the Hoody terminal service"
  },
  "servers": [
    {
      "url": "https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "summary": "Get web terminal interface",
        "parameters": []
      }
    },
    "/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"
      }
    }
  }
}

{}

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 and cURL

TypeScript SDK
cURL

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.docs.getJson();

curl "https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com/api/v1/terminal/openapi.json"

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

Returns the full OpenAPI 3.0 specification for the terminal service as YAML.

Response

openapi: 3.0.0
info:
  title: Hoody Terminal API
  version: 1.0.0
  description: HTTP API for the Hoody terminal service
servers:
  - url: https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com
paths:
  /:
    get:
      summary: Get web terminal interface
      parameters: []
  /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

{}

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 and cURL

TypeScript SDK
cURL

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.docs.getYaml();

curl "https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com/api/v1/terminal/openapi.yaml"