Terminal API

Setup and security

Enable Settings > Remote Control > Terminal API and generate a token. The server binds to 127.0.0.1, using port 3037 in production and 3036 in development. The general API is disabled by default. Keep it on loopback; it is not a public remote-access server.

Authorization: Bearer $TERMINAL_API_TOKEN
Content-Type: application/json

JSON success responses use { success: true, data: ... }; failures use { success: false, error: { code, message, reason?, details? } }. Branch on error.code. The general limit is 120 requests per 60 seconds per IP/method/path; exceeding it returns 429 RATE_LIMITED. Bootstrap challenge and webhook ingress are authentication exceptions described below.

Workspaces and sessions

{ "success": true, "data": { "workspaces": [
  { "id": "ws_123", "name": "my-project", "rootPath": "/path/to/project" }
] } }

For agent automation, set background: true to avoid taking a tab or pane. Foreground sessions can target paneId and use stealFocus: false; placement options cannot be combined with background: true (INVALID_PLACEMENT).

Session path targets accept an id or unique tab name; URL-encode names. An id wins over a matching name. Unresolved or ambiguous names return SESSION_NOT_FOUND; resolution failure returns SESSION_RESOLVE_FAILED. Resolve to an id for automation that must remain stable across renames. SSE resolves once when subscribing.

Input

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

queueUntilReady waits for readiness "idle". A readiness timeout returns TERMINAL_NOT_READY without writing. Invalid data returns 400 INVALID_INPUT_DATA; an invalid submitKey writes nothing. Input handling returns data.requestId on success or error.details.requestId on failure, except requests rejected before input handling.

A session held by a remote peer rejects /input, /submit, /keys, and /interrupt with 409 SESSION_HELD_BY_PEER. Take it over on this host before writing. Do not retry unchanged refusals.

Output and SSE

Responses include data.sessionId, mode, lines, cursor, nextCursor, hasMore, truncated, windowStart, windowEnd, and lineCount. Reuse nextCursor as since for incremental reads. screen has no since support; it prefers headless state, with DOM fallback requiring a visible pane. source=headless or source=dom forces that path. For content, chromeProfile accepts claude-code, default, or none.

Screen responses include outputHash and unchanged. Send ifHash on the next screen read; a matching hash returns unchanged: true with empty lines. waitForChange=true enables long polling; data.wait includes changed, timedOut, and optional reason: "LONGPOLL_TIMEOUT".

Terminal SSE does not replay a retained backlog. Recover missed history with /output?since=... before subscribing, then advance using payload.nextCursor. Slow readers can be disconnected.

Layout

curl -s -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:3037/api/terminal/layout?full=true" | jq .data.layout > layout.json
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d @layout.json \
  http://127.0.0.1:3037/api/terminal/layout/restore

Keep-alive and notifications

{ "rule": { "id": "review", "enabled": true,
  "schedule": { "kind": "interval", "intervalMs": 1800000 },
  "message": "continue" } }

At most 10 enabled rules per session. To read a live Prompt Library entry at each trigger, set message: "" and promptRef: { slug: "review", scope: "project" } (or scope: "global"). References and inline text are mutually exclusive; prompts must have no variables. Project references use the target’s local workspace. Invalid prompts skip the trigger. Rules are removed when the session is destroyed.

When sessionId is present and Discord supports session threads, the push targets Discord. Otherwise it uses connected remote providers. Without a session it goes to connected remotes. Success means at least one provider accepted delivery; an undelivered push returns a non-2xx response.

Agent sessions

This surface manages provider sessions and structured transcripts, separate from raw terminal sessions. Providers: claude, codex, agy, duo, opencode; gemini is accepted as an alias for agy and new responses use agy.

Callbacks target an existing AgentSession id or its terminal id/unique name. They never create or attach an agent and do not answer permission prompts. Keys do not deduplicate automatically; metadata is caller-supplied, not authenticated identity. Success acknowledges provider send, not task completion.

Service tokens

UI tokens have full access. Service tokens scope access to terminal and/or agent-session; omitting scopes grants both. Bootstrap provisioning works while the general API is disabled, but terminal and agent endpoints still return 403 DISABLED.

Webhook ingress

The URL is shown once and is a secret. The target must be an agent waiting at its input composer. Busy, missing, ambiguous, non-agent, or unreadable-screen targets fail without writing or creating a session. submit: true also sends Enter. Success is { success: true, data: { delivered: true } }.

For external senders, configure a TLS-enabled tunnel or reverse proxy exposing only /api/webhooks/... and keep secrets out of access logs. Never expose the other Terminal API routes. Revoke URLs in Settings.

Example: background terminal

BASE="http://127.0.0.1:3037"
AUTH="Authorization: Bearer $TERMINAL_API_TOKEN"
WS=$(curl -s -H "$AUTH" "$BASE/api/terminal/workspaces" | jq -r ".data.workspaces[0].id")
SID=$(curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \
  -d "{\"workspaceId\":\"$WS\",\"background\":true}" \
  "$BASE/api/terminal/sessions" | jq -r ".data.session.id")
curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"data":"pwd","appendEnter":true,"queueUntilReady":true}' \
  "$BASE/api/terminal/sessions/$SID/input"
curl -s -H "$AUTH" "$BASE/api/terminal/sessions/$SID/output?mode=text&lines=20"
curl -s -X DELETE -H "$AUTH" "$BASE/api/terminal/sessions/$SID"