Service terminal

The Service terminal API gives you a live shell inside a service's running container — the same PTY you get from the dashboard's Terminal tab on a service. You first mint a short-lived ticket over normal HTTP, then open a WebSocket that carries the ticket and streams keystrokes and output. It works in both deployment modes: on self-hosted instances it's a docker exec into the container; on Openship Cloud it's a shell in your Oblien workspace. The runtime is chosen automatically from the service's active deployment.

Mint a ticket

POST /api/services/terminal/ticket

Returns { success: true, token, expiresIn }. The token is single-use and expires after expiresIn seconds — mint it right before opening the socket. This route resolves the service and 404s early (before you burn a WebSocket attempt) if it doesn't exist, isn't yours, or has no active deployment yet.

curl -X POST "$OPENSHIP_URL/api/services/terminal/ticket" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"serviceId":"svc_123"}'

Open the WebSocket

GET /api/services/terminal/ws/:serviceId

Connect a WebSocket to this path. Because HTTP middleware that returned 401 would abort the handshake, this route is public at the HTTP layer and authenticates inside the upgrade instead. Two things gate it:

• Origin — the request Origin must be in the instance's trusted-origins allowlist, or the socket closes with 4403.
• Identity — pass the ticket from /ticket as a WebSocket subprotocol, prefixed with openship.terminal.v1+ (e.g. openship.terminal.v1+<token>). If no ticket is present, Openship falls back to the session cookie (dashboard case). To resume a parked session, add a second subprotocol prefixed with openship.terminal.resume+<resumeToken>.

Once open, the wire protocol is:

• Binary frames are raw PTY bytes — send keystrokes as binary; stdout/stderr arrive as binary.
• Text frames are JSON control messages. Client → server: {"type":"resize","cols":N,"rows":N} (cols clamped 1–1000, rows 1–500), {"type":"ping"}, {"type":"close"}. Server → client: {"type":"ready","sessionId","resumeToken","resumed"} on connect, {"type":"exit","code","signal"} when the shell ends, {"type":"error","code","message"}, and {"type":"pong"} (also sent as a heartbeat every ~25s).

# Mint a ticket, then connect with websocat, passing it as a subprotocol:
websocat "wss://your-host/api/services/terminal/ws/svc_123" \
  --protocol "openship.terminal.v1+$TICKET" \
  -H "Origin: $OPENSHIP_URL"

Errors

The WebSocket signals failures by sending an {"type":"error"} frame and then closing with a specific code:

Operations

SDK and CLI

Use client.terminal.openService(serviceId, { origin, onData }) for the same authenticated terminal protocol as server terminals. The session supports write, resize, close, and a closed promise with the confirmed exit result. See terminal transport.

openship service terminal <id> --project <project-id> opens an interactive PTY. Use openship service exec <id> "..." --project <project-id> for scripts; it preserves the remote command's exit status.