Terminal API 🟡 BETA

WebSocket-based terminal for interactive shell sessions

Base URL

/api/terminal

Authentication

All endpoints require a valid session token via Authorization: Bearer <token> header.

Endpoints

WebSocket Connection

GET /api/terminal/ws

Opens a WebSocket connection for an interactive terminal session.

Protocol:

• Connect via WebSocket to ws://host/api/terminal/ws?token=<session_token>
• Send JSON messages to execute commands
• Receive JSON messages with command output

Message Format (Client → Server):

{
  "type": "input",
  "data": "ls -la\n"
}

Message Format (Server → Client):

{
  "type": "output",
  "data": "total 48\ndrwxr-xr-x  6 user user 4096 Jan 15 10:30 .\n"
}

Message Types:

Resize Message:

{
  "type": "resize",
  "cols": 120,
  "rows": 40
}

List Sessions

GET /api/terminal/list

Returns all active terminal sessions.

Response:

{
  "success": true,
  "sessions": [
    {
      "id": "term-a1b2c3",
      "user_id": "u123",
      "pid": 45678,
      "started_at": "2026-01-15T10:30:00Z",
      "last_active": "2026-01-15T10:35:00Z",
      "status": "running"
    }
  ]
}

Create Session

POST /api/terminal/create

Creates a new terminal session without opening a WebSocket connection.

Request Body:

{
  "shell": "/bin/bash",
  "workdir": "/opt/gbo",
  "env": {
    "TERM": "xterm-256color"
  }
}

Response:

{
  "success": true,
  "session": {
    "id": "term-d4e5f6",
    "pid": 45679,
    "shell": "/bin/bash",
    "created_at": "2026-01-15T10:40:00Z"
  }
}

Kill Session

POST /api/terminal/kill

Terminates an active terminal session.

Request Body:

{
  "session_id": "term-a1b2c3"
}

Response:

{
  "success": true,
  "message": "Terminal session term-a1b2c3 terminated"
}

Error Responses

Usage Example

// Connect to terminal via WebSocket
const ws = new WebSocket('ws://localhost:8080/api/terminal/ws?token=mytoken');

ws.onopen = () => {
  // Send a command
  ws.send(JSON.stringify({ type: 'input', data: 'whoami\n' }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === 'output') {
    process.stdout.write(msg.data);
  }
};

// Resize terminal
ws.send(JSON.stringify({ type: 'resize', cols: 120, rows: 40 }));

See Also

• Security API — Command execution security and SafeCommand
• System API — System status and version checks