<!--
hoody-terminal Subskill (http)
Auto-generated by Hoody Skills Generator
Generated: 2026-06-20T00:43:07.928Z
Model: mimo-v2.5-pro
Mode: http


Tokens: 7231

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

# hoody-terminal Subskill

## 1. Overview (Service Philosophy & Purpose)

**hoody-terminal** is an HTTP-based terminal service that provides managed shell sessions. It turns terminal interactions into stateful, shareable HTTP endpoints.

**Core Concepts:**
- **Terminal as an Endpoint:** A terminal session is a persistent resource accessible via `terminal_id`. Commands are executed against a session and results are retrieved asynchronously.
- **Multiplayer by Default:** Multiple clients can connect to the same `terminal_id` concurrently, enabling real-time collaboration or monitoring.
- **Dual Execution Modes:**
    1.  **Direct Write:** Send raw keyboard input to the PTY via `POST /write`.
    2.  **Command Execution:** Execute a command and poll for its output via `POST /execute` and `GET /result/{command_id}`.

**When to Use This Service:**
- For any task that requires a persistent, interactive shell environment.
- To build automation tools that need to interact with a terminal (e.g., setup scripts, debugging agents).
- To provide a shared terminal experience for multiple users or agents.
- To programmatically manage system processes and resources on a container.

**Integration with Hoody Kit:**
This service runs as a container within a Hoody project. Its URL is derived from your project's container identifiers (see Base URL pattern below). Authentication is handled by the Hoody Proxy layer.

---

## 2. Common Workflows

### Workflow 1: Create Session, Execute Command, Get Result

This is the fundamental pattern for running a command.

**Step 1: Create a Terminal Session**
```
# The terminal_id can be a descriptive name or omitted for auto-creation
curl -s -X POST "https://{projectId}-{containerId}-terminal-{serviceId}.{node}.containers.hoody.com/api/v1/terminal/create" \
  -H "Content-Type: application/json" \
  -d '{
    "terminal_id": "setup-terminal"
  }'
```
*Response includes `terminal_id`. If the session already exists, it returns success.*

**Step 2: Execute a Command**
```
curl -s -X POST "https://{projectId}-{containerId}-terminal-{serviceId}.{node}.containers.hoody.com/api/v1/terminal/execute" \
  -H "Content-Type: application/json" \
  -d '{
    "terminal_id": "setup-terminal",
    "command": "ls -la /hoody/storage"
  }'
```
*Response includes a `command_id` to track the execution.*

**Step 3: Retrieve Command Result**
```
# Poll this endpoint until the status is 'completed' or 'failed'
curl -s "https://{projectId}-{containerId}-terminal-{serviceId}.{node}.containers.hoody.com/api/v1/terminal/result/{command_id}"
```
*Response contains the exit code, stdout, and stderr once the command finishes.*

**Step 4: Get Session History**
```
# View all commands run in this session
curl -s "https://{projectId}-{containerId}-terminal-{serviceId}.{node}.containers.hoody.com/api/v1/terminal/history/{terminal_id}"
```

### Workflow 2: Interactive Input & Real-time Output

For commands requiring sequential input or for building a real-time REPL.

**Step 1: Write Input (like typing)**
```
# This writes 'python3\n' to the terminal
curl -s -X POST "https://{projectId}-{containerId}-terminal-{serviceId}.{node}.containers.hoody.com/api/v1/terminal/write" \
  -H "Content-Type: application/json" \
  -d '{
    "terminal_id": "setup-terminal",
    "input": "python3"
  }'
```

**Step 2: Use WebSocket for Real-time Stream**
```
// In a client that supports WebSockets
const ws = new WebSocket(`wss://{projectId}-{containerId}-terminal-{serviceId}.{node}.containers.hoody.com/api/v1/terminal/ws?terminal_id=setup-terminal`);
// Listen for binary frames containing terminal output
```

### Workflow 3: Automation & Waiting for State

Wait for specific patterns in the terminal output before proceeding.

**Step 1: Wait for a Prompt**
```
curl -s -X POST "https://{projectId}-{containerId}-terminal-{serviceId}.{node}.containers.hoody.com/api/v1/terminal/wait" \
  -H "Content-Type: application/json" \
  -d '{
    "terminal_id": "setup-terminal",
    "mode": "regex",
    "pattern": "\\$",
    "timeout": 30
  }'
```
*The call blocks until the `>` or `$` prompt appears in the terminal output.*

**Step 2: Capture a Screenshot**
```
# Saves a PNG to /hoody/storage and returns the image data
curl -s "https://{projectId}-{containerId}-terminal-{serviceId}.{node}.containers.hoody.com/api/v1/terminal/screenshot?terminal_id=setup-terminal" --output screenshot.png
```

### Workflow 4: System Monitoring & Process Control

**List All Processes:**
```
curl -s "https://{projectId}-{containerId}-terminal-{serviceId}.{node}.containers.hoody.com/api/v1/system/processes"
```

**Send a Signal to a Process:**
```
curl -s -X POST "https://{projectId}-{containerId}-terminal-{serviceId}.{node}.containers.hoody.com/api/v1/system/process/signal" \
  -H "Content-Type: application/json" \
  -d '{
    "pid": 1234,
    "signal": "SIGTERM"
  }'
```

**Check System Resources:**
```
curl -s "https://{projectId}-{containerId}-terminal-{serviceId}.{node}.containers.hoody.com/api/v1/system/resources"
```

---

## 3. Advanced Operations

### Multi-Client Session Collaboration
Multiple agents can connect to the same `terminal_id`.
1.  Agent A creates and owns the session via `POST /create`.
2.  Agent B uses `POST /write` to send commands to the same `terminal_id`.
3.  Both agents can use `GET /snapshot` or `GET /ws` to see the same output. State is synchronized by the server.

### Error Recovery & Session Cleanup
- **Command Failure:** Always check `exit_code` in the response from `GET /result/{command_id}`.
- **Session Hanging:** If a command is stuck, abort it:
  ```
  curl -s -X POST "https://{projectId}-{containerId}-terminal-{serviceId}.{node}.containers.hoody.com/api/v1/terminal/execute/{command_id}/abort" \
    -H "Content-Type: application/json" \
    -d '{
      "mode": "force"
    }'
  ```
- **Clean Session Teardown:** To avoid resource leaks, explicitly destroy sessions you create.
  ```
  curl -s -X DELETE "https://{projectId}-{containerId}-terminal-{serviceId}.{node}.containers.hoody.com/api/v1/terminal/setup-terminal"
  ```

### Performance & Concurrency Considerations
- The `POST /execute` endpoint is non-blocking; the `command_id` is returned immediately. Poll `GET /result` to check status.
- Use `GET /terminal/automation/metrics` to monitor server-side resource usage for VT parsing and active sessions.
- For high-frequency automation, prefer the `POST /execute` + `GET /result` pattern over raw `POST /write`, as it provides clear command boundaries and exit status.
- Be mindful of session limits. Destroy sessions that are no longer needed.

---

## 4. Quick Reference

**Most Common Endpoints:**
| Method | Path | Purpose |
|--------|------|---------|
| `POST` | `/api/v1/terminal/create` | Create/ensure a session exists. |
| `POST` | `/api/v1/terminal/execute` | Run a command in a session. |
| `GET` | `/api/v1/terminal/result/{command_id}` | Get the output/exit code of a command. |
| `POST` | `/api/v1/terminal/write` | Send raw keyboard input. |
| `GET` | `/api/v1/terminal/sessions` | List all active sessions. |
| `GET` | `/api/v1/system/resources` | Get CPU, memory, disk stats. |
| `GET` | `/api/v1/terminal/health` | Service health check (unauthenticated). |

**Essential Parameters:**
- `terminal_id` (string): The unique identifier for a terminal session. Can be auto-generated if omitted from `POST /create`.
- `command` (string): The shell command to execute. Required for `POST /execute`.
- `command_id` (string): The unique ID for a specific command execution, returned by `POST /execute`. Required for `GET /result` and `POST /abort`.
- `mode` (string): For `POST /wait`, can be `stable`, `regex`, or `fixed`.

**Typical Response Formats:**
- **Health:** `{ "status": "healthy", "service": "hoody-terminal", ... }` (9-field standard object)
- **Execution Result:** `{ "command_id": "...", "status": "completed", "exit_code": 0, "stdout": "...", "stderr": "..." }`
- **Session List:** `[ { "terminal_id": "...", "created_at": "...", "pid": 123 } ]`
- **Process List:** `[ { "pid": 1, "name": "bash", "cpu": 0.5, "memory": 1.2 } ]`