HTTP API

The web viewer exposes an HTTP API on port 8081 (configurable).

Authentication

Most endpoints require session-based authentication. Login via /api/login with OS credentials to receive a session cookie.

Endpoints

Public Endpoints

Method	Path	Description
GET	/health	GET /health - Health check (no auth required).
GET	/login	Serve login.html page with version injection.
GET	/auth/token/{token}	GET /auth/token/{token} - One-time login via magic link.
GET	/api/security-context	GET /api/security-context - Check if login is allowed (secure context).

Protected Endpoints

These endpoints require authentication.

Method	Path	Description
POST	/api/login	POST /api/login - Authenticate user with OS credentials.
POST	/api/logout	POST /api/logout - Destroy session and clear cookie.
GET	/api/whoami	GET /api/whoami - Get current user info.
POST	/api/log	POST /api/log - Receive log messages from frontend.
GET	/api/sessions	GET /api/sessions - List available tmux sessions.
GET	/api/session/{session_id}	GET /api/session/{session_id} - Get session details.
GET	/api/capture/{session_id}	GET /api/capture/{session_id} - Capture session as PNG.
GET	/api/scroll/{session_id}	GET /api/scroll/{session_id} - Capture scrollback buffer as PNG.
POST	/api/resize/{session_id}	POST /api/resize/{session_id} - Resize terminal for a session.
GET	/	Serve index.html with version injection and no-cache headers.
GET	/static/{filename:.*}	Serve static files with no-cache headers.

Endpoint Details

GET /health

Health check endpoint. Returns server status and client version.

Response:

{
  "status": "ok",
  "client_version": "2026020615"
}

POST /api/login

Authenticate with OS credentials.

Request:

{
  "username": "user",
  "password": "password",
  "force": false
}

Response:

{
  "success": true,
  "username": "user"
}

If another session exists and force is false:

{
  "success": false,
  "session_exists": true,
  "existing_session": {
    "ip": "192.168.1.100",
    "hostname": "other-device.local",
    "location": "Local Network"
  }
}

GET /api/sessions

List all tmux sessions with detection info.

Response:

{
  "hostname": "macbook",
  "sessions": [
    {
      "session_id": "$0",
      "session_name": "coding-0",
      "created_at": 1707321600,
      "attached": false,
      "windows": 1,
      "cwd": "/home/user/project",
      "program": "Claude Code",
      "state": "Idle"
    }
  ]
}

GET /api/capture/{session_id}

Capture terminal as PNG image.

Response: image/png

GET /api/scroll/{session_id}

Capture scrollback buffer.

Query Parameters: - max_lines: Maximum lines to capture (default: 500, max: 2000)

Response:

{
  "type": "scroll_response",
  "png_base64": "iVBORw0KGgo...",
  "total_lines": 500,
  "pane_height": 24,
  "history_size": 2000,
  "cols": 80,
  "retina": true
}

POST /api/resize/{session_id}

Resize terminal dimensions.

Request:

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

Response:

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