Terminal API

Local HTTP API for AI agents to create and control terminal sessions programmatically. Designed for agentic workflows with Claude Code, Cursor, and other AI tools.

Overview

The Terminal API exposes a local HTTP server that AI agents can use to create terminal sessions, send commands, read output, and manage session lifecycles. It runs on localhost only and requires token-based authentication.

Setup

  1. In Termdock: Settings > Remote Control > Terminal API > enable the API server.
  2. Click Generate Token to create an API token.
  3. The server runs on:
    Dev: localhost:3036Prod: localhost:3037

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer $TERMINAL_API_TOKEN

Rate Limiting

120 requests per 60 seconds per IP/method/path combination. Exceeding the limit returns 429 Too Many Requests.

Endpoints

GET/api/terminal/workspaces

List all available workspaces.

Response:

{ "workspaces": [
    { "id": "ws-1", "name": "my-project", "path": "/home/user/my-project" }
  ]
}
POST/api/terminal/sessions

Create a new terminal session.

Request body:

{ "workspaceId": "ws-1", "logPolicy": "persist" }

Response:

{ "sessionId": "zsh-abc123", "status": "running" }
GET/api/terminal/sessions

List all active terminal sessions.

GET/api/terminal/sessions/:id/status

Get session status including running state and metadata.

GET/api/terminal/sessions/:id/log

Retrieve session log. Only available when logPolicy="persist".

POST/api/terminal/sessions/:id/input

Send input to a terminal session.

Request body:

{ "data": "ls -la", "appendEnter": true }
GET/api/terminal/sessions/:id/output

Read terminal output.

Query parameters:

mode       = text | raw | content
lines      = 50           (number of lines)
since      = <timestamp>  (only output after this time)
waitForChange = true      (long-poll until new output)
timeoutMs  = 10000        (long-poll timeout)
POST/api/terminal/sessions/:id/keys

Send special keys (ctrl+c, enter, tab, up, down, esc) to a session.

DELETE/api/terminal/sessions/:id

Destroy a terminal session and release resources.

Output Modes

text

Strips ANSI escape codes. Clean plain text suitable for LLM consumption.

raw

Preserves all ANSI sequences. Use when you need color or formatting data.

content

Filters out TUI chrome (progress bars, spinners). Best for extracting meaningful output.

Example: Agent Workflow

A typical AI agent workflow using curl:

# 1. Create a session
curl -X POST http://localhost:3037/api/terminal/sessions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId": "ws-1"}'

# 2. Send a command
curl -X POST http://localhost:3037/api/terminal/sessions/zsh-abc123/input \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data": "npm test", "appendEnter": true}'

# 3. Poll for output
curl "http://localhost:3037/api/terminal/sessions/zsh-abc123/output?mode=text&lines=100" \
  -H "Authorization: Bearer $TOKEN"

# 4. Clean up
curl -X DELETE http://localhost:3037/api/terminal/sessions/zsh-abc123 \
  -H "Authorization: Bearer $TOKEN"