headquarter/docs/api/terminal.md

Terminal API

The Terminal API provides WebSocket-based terminal access to running tool instances.

WebSocket Endpoint

Connect to Terminal

GET /ws/tool-instances/{instance_id}/terminal

Establishes a WebSocket connection to an interactive terminal session inside a running tool instance container.

Authentication: Requires valid session cookie.

Path Parameters:

• instance_id (string, UUID): The tool instance ID

Connection Flow:

1. Client connects to WebSocket endpoint
2. Server authenticates user and verifies instance ownership
3. Server creates or reattaches to existing terminal session
4. Server sends {"type": "status", "status": "connected"} message
5. Bidirectional communication begins

Message Types:

Client to Server

Terminal Input (bytes or string)

• Send raw bytes for terminal input (key presses)
• Send text for terminal input (will be encoded as UTF-8)

Resize Command (JSON)

{
  "type": "resize",
  "cols": 80,
  "rows": 24
}

Reset Command (JSON)

{
  "type": "reset"
}

Kills the current terminal session and starts a fresh one.

Pong Response (JSON)

{
  "type": "pong"
}

Sent automatically in response to server ping messages.

Server to Client

Terminal Output (bytes) Raw terminal output as binary data (Blob in browser).

Status Messages (JSON)

{"type": "status", "status": "connected"}
{"type": "status", "status": "resetting"}

Ping Messages (JSON)

{"type": "ping"}

Sent every 30 seconds to detect disconnections. Client should respond with {"type": "pong"}.

Session Persistence

Terminal sessions persist across WebSocket disconnections:

• When a client disconnects, the terminal session remains active
• On reconnection, the client reattaches to the existing session
• Buffered output is replayed to the client on reconnection
• Sessions are cleaned up after 30 minutes of inactivity

Concurrent Connections

Only one WebSocket connection is allowed per terminal session:

• New connections close existing connections with code 4000
• Previous client receives "New connection established" reason

HTTP Endpoints

Reset Terminal Session

POST /api/projects/{project_id}/repositories/{repo_id}/instances/{instance_id}/terminal/reset

Resets the terminal session for a tool instance, killing the current shell and starting fresh.

Authentication: Required

Path Parameters:

• project_id (string, UUID): Project ID
• repo_id (string, UUID): Repository ID
• instance_id (string, UUID): Instance ID

Response:

{
  "status": "success",
  "message": "Terminal session reset successfully",
  "instance_id": "...",
  "session_id": "..."
}

Error Responses:

• 404 Not Found: Instance not found
• 400 Bad Request: Instance is not running
• 500 Internal Server Error: Failed to reset terminal session

Error Codes

WebSocket close codes:

• 1000: Normal closure
• 4000: Error/reset
• 4001: Invalid instance ID
• 4003: Unauthorized/Forbidden
• 4004: Instance not found or not running

Heartbeat

The server sends ping messages every 30 seconds. If no ping is received for 60 seconds, the client should assume the connection is dead and reconnect.