Terminal API

讓 AI agent 以程式化方式建立並控制終端 session 的本地 HTTP API。專為 Claude Code、Cursor 等 AI 工具的 agentic 工作流設計。

總覽

Terminal API 提供一個本地 HTTP server，AI agent 可以用它建立終端 session、傳送指令、讀取輸出、管理 session 生命週期。只綁定 localhost，且必須通過 token 認證。

設定

在 Termdock：設定 > 遠端控制 > Terminal API > 啟用 API server。
點 Generate Token 產生 API token。
Server 運行在：
開發：localhost:3036正式：localhost:3037

認證

所有請求都要在 Authorization header 帶 Bearer token：

Authorization: Bearer $TERMINAL_API_TOKEN

速率限制

每個 IP/method/path 組合 60 秒內 120 次請求。超限回傳 429 Too Many Requests。

端點

GET/api/terminal/workspaces

列出所有可用的 workspace。

回應：

{ "workspaces": [
    { "id": "ws_123", "name": "my-project", "rootPath": "/home/user/my-project" }
  ]
}

POST/api/terminal/sessions

建立新的終端 session。workspaceId 為必填；可選：cols（80-500）、rows（24-100）、 name、logPolicy、 background。agent 要讀長指令回顯時建議放寬 cols（例如 300）。

Request body：

{ "workspaceId": "ws_123", "cols": 300, "logPolicy": "persist" }

回應：

{ "success": true,
  "data": { "session": {
    "id": "terminal-pty-123", "name": "my-session",
    "status": "running", "isActive": true, "background": false
  } }
}

GET/api/terminal/sessions

列出所有運作中的終端 session。

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

取得 session 狀態，含運行狀態與 metadata。

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

讀取 session log。只在 logPolicy="persist" 時可用。

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

傳送輸入到終端 session。一般指令提交用 appendEnter: true。帶 queueUntilReady: true 時，寫入會暫存到終端閒置才送出，超過 readyTimeoutMs 仍未就緒則回 TERMINAL_NOT_READY。

Request body：

{ "data": "npm test", "appendEnter": true, "queueUntilReady": true, "readyTimeoutMs": 30000 }

GET/api/terminal/sessions/:id/output

讀取終端輸出。

Query 參數：

mode       = text | raw | content | screen
lines      = 50           (行數)
since      = <cursor>     (輸出游標；帶上次回應的 nextCursor)
waitForChange = true      (long-poll 等待新輸出)
timeoutMs  = 10000        (long-poll 逾時)

POST/api/terminal/sessions/:id/keys

傳送特殊鍵到 session：enter、 up、down、 left、right、 tab、esc、 ctrl+c、ctrl+d。

POST/api/terminal/sessions/:id/submit

在 session 已處於互動提示狀態（TUI 輸入框、y/n 確認）時提交輸入 — 套用 Termdock 處理互動輸入的同一條 settle 路徑。支援 settleMs 與 queueUntilReady。不是每個一般指令後的預設後續動作。

GET/api/terminal/sessions/:id/events

Session 輸出事件的 Server-Sent Events 串流（output.new）。接受 mode=raw|text|content（screen 會被拒絕 — 它的游標是畫面相對而非歷史相對）。termdock session output --follow 背後就是它。

POST/api/terminal/sessions/:id/interrupt

對前景程序送出 Ctrl+C，但不銷毀 session（v1.9+）。

GET/api/terminal/sessions/:id/ports

列出該 session 程序監聽中的 port（v1.15+）。終端分頁上的 port 標籤用的就是同一份資料。

DELETE/api/terminal/sessions/:id

銷毀終端 session 並釋放資源。

版面端點

以程式化方式控制窗格版面（v1.6.2+）。termdock layout 背後就是這組介面。

GET  /api/terminal/layout                          # 當前版面與窗格指派
POST /api/terminal/layout                          # 設定版面類型 / session 對應
POST /api/terminal/layout/panes/:paneId/assign     # 指派 session 到窗格
POST /api/terminal/layout/panes/:paneId/activate   # 聚焦窗格

Agent Sessions

受管的 AI agent session（v1.9+），支援 claude、 codex、gemini。 Termdock 在終端中啟動 agent CLI、追蹤生命週期（派工狀態、存活 metadata），並提供結構化讀取，不必自己刮畫面。

POST   /api/agent-sessions                    # 建立：{ provider, cwd, prompt }
POST   /api/agent-sessions/attach             # 接上：{ provider, sessionId, cwd }
POST   /api/agent-sessions/resolve            # 解析 session 目標
GET    /api/agent-sessions                    # 列表
GET    /api/agent-sessions/:id                # 狀態與生命週期 metadata
POST   /api/agent-sessions/:id/input          # 傳送後續 prompt
POST   /api/agent-sessions/:id/interrupt      # 軟中斷進行中的回合
POST   /api/agent-sessions/:id/restart        # 重啟 agent 程序
GET    /api/agent-sessions/:id/events         # SSE 生命週期事件
GET    /api/agent-sessions/:id/rendered       # 渲染畫面快照
GET    /api/agent-sessions/:id/rendered/stream # SSE 渲染畫面串流
POST   /api/agent-sessions/hooks              # 匯入 provider hook 事件（v1.13+）
DELETE /api/agent-sessions/:id                # 終止並釋放

建立的 request body：

{ "provider": "claude", "cwd": "/home/user/my-project", "prompt": "Fix the failing tests" }

Service Tokens

給 daemon 用的長效 token（v1.9+），與 UI 產生的 token 分離。scope 可設 terminal 與/或 agent-session （省略則兩者都給）。可用本地 bootstrap secret（ ~/.termdock/config/terminal-api-bootstrap.json）搭配 X-Termdock-Bootstrap-Token header 鑄造，或用 UI token。輪替支援 graceSeconds 寬限期；service token 只能輪替或撤銷自己。

POST   /api/auth/service-tokens              # 建立 service token
POST   /api/auth/service-tokens/:id/rotate   # 輪替 token
DELETE /api/auth/service-tokens/:id          # 撤銷 token

輸出模式

text

去除 ANSI escape code 的乾淨純文字，適合餵給 LLM。

raw

保留全部 ANSI 序列。需要顏色或格式資訊時用。

content

過濾 TUI 雜訊（進度條、spinner）。適合萃取有意義的輸出。

screen

當前可見畫面狀態，headless 優先讀取、DOM 為 fallback（v1.15+）。最適合監看 TUI。回應含 outputHash；下次帶 ifHash 可低成本取得 unchanged: true。

範例：Agent 工作流

典型的 AI agent 工作流（curl）：

# 1. 取得 workspace id
WS=$(curl -s http://localhost:3037/api/terminal/workspaces \
  -H "Authorization: Bearer $TOKEN" | jq -r '.data.workspaces[0].id')

# 2. 建立 session（id 在 .data.session.id）
SID=$(curl -s -X POST http://localhost:3037/api/terminal/sessions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"workspaceId\": \"$WS\"}" | jq -r '.data.session.id')

# 3. 傳送指令（暫存到 shell 閒置才送出）
curl -s -X POST http://localhost:3037/api/terminal/sessions/$SID/input \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data": "npm test", "appendEnter": true, "queueUntilReady": true}'

# 4. 輪詢輸出（保存 .data.nextCursor 給下次輪詢）
curl -s "http://localhost:3037/api/terminal/sessions/$SID/output?mode=text&lines=100" \
  -H "Authorization: Bearer $TOKEN"

# 5. 清理
curl -s -X DELETE http://localhost:3037/api/terminal/sessions/$SID \
  -H "Authorization: Bearer $TOKEN"