Skip to main content

​
API Reference

​
Base URL

  • Development: http://localhost:4020
  • Production: Configurable via settings

​
Authentication

​
Token Generation

POST /api/auth/token
Content-Type: application/json

{
  "password": "optional-password"
}
Response 
{
  "token": "jwt-token-string",
  "expiresIn": 86400
}

​
Session Management

​
Create Session

POST /api/sessions
Authorization: Bearer <token>
Content-Type: application/json

{
  "command": "zsh",
  "args": [],
  "cwd": "/Users/username",
  "env": {},
  "name": "Session Name",
  "cols": 80,
  "rows": 24
}
Response 
{
  "id": "session-uuid",
  "name": "Session Name",
  "created": "2024-01-01T00:00:00Z",
  "status": "running",
  "pid": 12345
}

​
List Sessions

GET /api/sessions
Authorization: Bearer <token>
Response 
[
  {
    "id": "session-uuid",
    "name": "Session 1",
    "created": "2024-01-01T00:00:00Z",
    "status": "running",
    "pid": 12345
  }
]

​
Get Session Details

GET /api/sessions/:id
Authorization: Bearer <token>

​
Delete Session

DELETE /api/sessions/:id
Authorization: Bearer <token>

​
Resize Terminal

POST /api/sessions/:id/resize
Authorization: Bearer <token>
Content-Type: application/json

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

​
WebSocket Connection

​
WebSocket v3 (/ws)

  • Endpoint: GET /ws (WebSocket upgrade)
  • Framing: binary v3 frames ("VT" magic, version 3, type, sessionId, payload)
  • Multiplexing: one socket carries multiple session subscriptions
Protocol details: docs/websocket.md. 
const ws = new WebSocket('ws://localhost:4020/ws?token=JWT_TOKEN');
ws.binaryType = 'arraybuffer';

​
Health Check

​
Server Status

GET /api/health
Response 
{
  "status": "healthy",
  "uptime": 3600,
  "version": "1.0.0",
  "sessions": 5
}

​
Error Responses

StatusErrorDescription
400Bad RequestInvalid parameters
401UnauthorizedMissing/invalid token
404Not FoundSession not found
409ConflictSession already exists
500Server ErrorInternal error
Error Format 
{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {}
}

​
Rate Limiting

  • Session Creation: 10 per minute
  • API Calls: 100 per minute
  • WebSocket Messages: Unlimited

​
Terminal Transport (WebSocket v3)

Terminal I/O uses a single /ws WebSocket with binary v3 framing and multiplexed sessions. Details: docs/websocket.md.

​
Session Recording

Sessions are recorded in asciinema v2 format: 
{
  "version": 2,
  "width": 80,
  "height": 24,
  "timestamp": 1234567890,
  "env": {
    "SHELL": "/bin/zsh",
    "TERM": "xterm-256color"
  }
}
Event format: 
[timestamp, "o", "output data"]

​
See Also