# Terminal: Web UI & API Access
**Page:** api/terminal/web-interface
[Download Raw Markdown](./api/terminal/web-interface.md)
---
{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}
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
```html
Hoody Terminal
```
### SDK Usage
```typescript
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
```json
{
"openapi": "3.0.0",
"info": {
"title": "Hoody Terminal API",
"version": "1.0.0"
},
"paths": {},
"components": {}
}
```
```json
{}
```
| 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
```typescript
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
```yaml
openapi: 3.0.0
info:
title: Hoody Terminal API
version: 1.0.0
paths: {}
components: {}
```
```json
{}
```
| 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
```typescript
const specYaml = await client.terminal.docs.getYaml();
```