<!--
hoody-terminal Subskill (http)
Auto-generated by Hoody Skills Generator
Generated: 2026-05-06T18:28:28.548Z
Model: mimo-v2.5-pro + fixer:mimo-v2.5-pro
Mode: http


Tokens: 7745

DO NOT EDIT MANUALLY - Changes will be overwritten on next generation
-->

# hoody-terminal Subskill

## Overview

**hoody-terminal** provides HTTP-accessible terminal sessions that are multiplayer by default. Every terminal session is exposed as a REST endpoint, enabling command execution, screen reading, keyboard input, and real-time WebSocket I/O — all over standard HTTP.

### When to Use

- **Remote command execution**: Run shell commands in container terminals via REST
- **Terminal automation**: Programmatically interact with TUI applications (vim, htop, etc.)
- **System monitoring**: Inspect processes, ports, resources, and display state
- **Multiplayer collaboration**: Share terminal sessions between multiple clients
- **Screenshot & audit**: Capture terminal state as images or raw text

### How It Fits Hoody Philosophy

Terminal sessions are HTTP endpoints — no SSH keys, no port forwarding. Sessions are multiplayer by default: multiple clients connect to the same `terminal_id` via WebSocket or REST. Commands execute synchronously or asynchronously. The service bridges traditional terminal interaction with modern API-driven workflows.

### Base URL

```
https://{projectId}-{containerId}-terminal-{serviceId}.{node}.containers.hoody.icu
```

All paths below are relative to this base URL. Do **not** prepend `/api/v1` to paths that don't include it (e.g., `/health` is at the root).

---

## Common Workflows

### 1. Health Check

Verify the terminal service is running. Unauthenticated. Always returns HTTP 200.

```
BASE_URL="https://{projectId}-{containerId}-terminal-{serviceId}.{node}.containers.hoody.icu"

curl -s "$BASE_URL/api/v1/terminal/health"
```

Response:

```
{
  "status": "ok",
  "service": "hoody-terminal",
  "version": "1.0.0",
  "uptime": 3600,
  "timestamp": "2025-01-15T10:30:00Z",
  "environment": "production",
  "region": "us-east-1",
  "node": "node-01",
  "container": "abc123"
}
```

### 2. Create a Terminal Session

Create a new terminal session. Returns session metadata. If the session already exists, returns success.

```
curl -s -X POST "$BASE_URL/api/v1/terminal/create" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Response:

```
{
  "terminal_id": "term-abc123",
  "status": "created",
  "created_at": "2025-01-15T10:30:00Z"
}
```

Save the `terminal_id` — all subsequent operations require it.

### 3. Execute a Command (Async)

Execute a command in a terminal session. Returns a `command_id` for polling results.

```
curl -s -X POST "$BASE_URL/api/v1/terminal/execute" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "ls -la /hoody"
  }'
```

Response:

```
{
  "command_id": "cmd-xyz789",
  "terminal_id": "term-abc123",
  "status": "running"
}
```

### 4. Get Command Result

Poll for command output. Can be called while running or after completion.

```
curl -s "$BASE_URL/api/v1/terminal/result/cmd-xyz789"
```

Response:

```
{
  "command_id": "cmd-xyz789",
  "status": "completed",
  "exit_code": 0,
  "stdout": "total 12\ndrwxr-xr-x 3 root root 4096 Jan 15 10:00 .\n",
  "stderr": "",
  "started_at": "2025-01-15T10:30:01Z",
  "finished_at": "2025-01-15T10:30:01Z"
}
```

### 5. Get Terminal History

Retrieve all commands executed in a session.

```
curl -s "$BASE_URL/api/v1/terminal/history/term-abc123"
```

### 6. List Active Sessions

See all running terminal sessions.

```
curl -s "$BASE_URL/api/v1/terminal/sessions"
```

Response:

```
[
  {
    "terminal_id": "term-abc123",
    "created_at": "2025-01-15T10:30:00Z",
    "status": "active"
  }
]
```

### 7. Destroy a Terminal Session

Completely remove a session, kill running processes, free resources.

```
curl -s -X DELETE "$BASE_URL/api/v1/terminal/term-abc123"
```

### 8. Abort a Running Command

Cancel a command gracefully (SIGINT) or forcefully (SIGKILL).

```
curl -s -X POST "$BASE_URL/api/v1/terminal/execute/cmd-xyz789/abort" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### 9. Write Keyboard Input

Send raw keystrokes to a terminal session's PTY.

```
curl -s -X POST "$BASE_URL/api/v1/terminal/write?terminal_id=term-abc123" \
  -H "Content-Type: application/json" \
  -d '{"input": "hello\\n"}'
```

### 10. Get Raw Terminal Output

Retrieve the terminal output buffer in text or other formats.

```
curl -s "$BASE_URL/api/v1/terminal/raw?terminal_id=term-abc123"
```

### 11. Capture Screenshot

Convert terminal ANSI output to an image. Saved to `/hoody/storage/hoody-terminal/screenshots/{terminal_id}/`.

```
curl -s "$BASE_URL/api/v1/terminal/screenshot?terminal_id=term-abc123"
```

---

## Advanced Operations

### Terminal Automation

#### Get Terminal Snapshot

Returns the rendered screen as a text grid with cursor position and metadata.

```
curl -s "$BASE_URL/api/v1/terminal/snapshot?terminal_id=term-abc123"
```

Response:

```
{
  "lines": ["Welcome to Ubuntu 22.04", "user@host:~$ "],
  "cursor": {"row": 1, "col": 12},
  "title": "user@host:~",
  "alt_screen": false,
  "width": 80,
  "height": 24
}
```

#### Search Terminal Screen

Find a PCRE2 regex pattern in the rendered screen or scrollback.

```
curl -s "$BASE_URL/api/v1/terminal/find?terminal_id=term-abc123&pattern=error"
```

#### Wait for Condition

Block until a terminal condition is met. Three modes: `stable`, `regex`, `idle`.

```
curl -s -X POST "$BASE_URL/api/v1/terminal/wait?terminal_id=term-abc123" \
  -H "Content-Type: application/json" \
  -d '{"mode": "stable", "duration": 2}'
```

#### Send Key Presses

Send named keys (Enter, Tab, Escape, arrows, function keys) respecting terminal modes.

```
curl -s -X POST "$BASE_URL/api/v1/terminal/press?terminal_id=term-abc123" \
  -H "Content-Type: application/json" \
  -d '{"keys": ["Enter"]}'
```

#### Paste Text

Paste text with optional bracketed paste mode.

```
curl -s -X POST "$BASE_URL/api/v1/terminal/paste?terminal_id=term-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "echo hello world"
  }'
```

#### List Supported Keys

Get all key names accepted by the press endpoint.

```
curl -s "$BASE_URL/api/v1/terminal/keys"
```

#### Get Automation Metrics

Monitor VT parser resource usage across all sessions.

```
curl -s "$BASE_URL/api/v1/terminal/automation/metrics"
```

#### Get Session Automation State

View VT parser state for a specific session.

```
curl -s "$BASE_URL/api/v1/terminal/term-abc123/automation"
```


### Process Management

#### Send Signal to Process

Send any Unix signal by PID or process name.

```
curl -s -X POST "$BASE_URL/api/v1/system/process/signal" \
  -H "Content-Type: application/json" \
  -d '{"pid": 1234, "signal": "SIGTERM"}'
```

#### System Shutdown

```
curl -s -X POST "$BASE_URL/api/v1/system/shutdown" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### System Reboot

```
curl -s -X POST "$BASE_URL/api/v1/system/reboot" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### WebSocket Connection

Establish real-time bidirectional terminal I/O. Multiple clients share the same session.

```
curl -s "$BASE_URL/api/v1/terminal/ws?terminal_id=term-abc123"
```

### Web Interface

Open the browser-based terminal UI.

```
GET /
```

Supports URL parameters for session management, display settings, and SSH connections.

### API Documentation

```
curl -s "$BASE_URL/api/v1/terminal/openapi.json"
curl -s "$BASE_URL/api/v1/terminal/openapi.yaml"
```

---

## Quick Reference

### Most Common Endpoints

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/v1/terminal/health` | Health check |
| POST | `/api/v1/terminal/create` | Create session |
| POST | `/api/v1/terminal/execute` | Run command |
| GET | `/api/v1/terminal/result/{command_id}` | Get command output |
| GET | `/api/v1/terminal/sessions` | List sessions |
| DELETE | `/api/v1/terminal/{terminal_id}` | Destroy session |
| GET | `/api/v1/terminal/snapshot` | Screen state |
| POST | `/api/v1/terminal/wait` | Wait for condition |
| WS | `/api/v1/terminal/ws` | WebSocket I/O |

### Essential Parameters

| Parameter | Type | Used By |
|-----------|------|---------|
| `terminal_id` | string (query) | Most terminal endpoints |
| `command_id` | string (query/path) | result, abort |
| `command` | string (body) | execute |
| `text` | string (body) | paste |
| `pattern` | string (query) | find |

### Typical Workflow Sequence

```
1. POST /api/v1/terminal/create          → get terminal_id
2. POST /api/v1/terminal/execute          → get command_id
3. GET  /api/v1/terminal/result/{cmd_id}  → poll until completed
4. GET  /api/v1/terminal/snapshot         → verify screen state
5. DELETE /api/v1/terminal/{terminal_id}  → cleanup
```

### Response Patterns

- **Health**: Always HTTP 200, 9-field JSON object
- **Sessions**: JSON array of session objects
- **Commands**: JSON with `status` field (`running`, `completed`, `failed`)
- **Snapshots**: JSON with `lines` array and `cursor` object
- **Errors**: HTTP 4xx/5xx with error message in response body