Service terminal API
Open an interactive shell into a running service container over a WebSocket, authenticated by a one-shot ticket.
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.
Base path & auth
All paths are relative to your instance, under /api — the base is /api/services/terminal. Mint the
ticket with a personal access token as a bearer header (Authorization: Bearer <token>), created with
openship token create; the dashboard uses your session cookie instead. The WebSocket
upgrade itself carries no bearer header — auth happens inside the handshake (see below). See the
API overview and auth model for details.
Endpoints
| Method & path | Permission | What it does |
|---|---|---|
POST /api/services/terminal/ticket | terminal:write | Mint a one-shot, short-lived WebSocket auth ticket for a service. |
GET /api/services/terminal/ws/:serviceId | public | WebSocket upgrade — auth happens inside the handshake (ticket subprotocol or session cookie). |
Both routes require admin on the project
Opening a service shell is admin-tier: it's full reach into the container. Beyond the terminal:write tag
on the ticket route, both endpoints check that the caller has admin permission on the service's parent
project. A service you can't administer (or that isn't in your active organization) returns 404 — Openship
never confirms its existence to non-admins.
Mint a ticket
POST /api/services/terminal/ticketProp
Type
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 https://your-host/api/services/terminal/ticket \
-H "Authorization: Bearer $OPENSHIP_TOKEN" \
-H "Content-Type: application/json" \
-d '{"serviceId":"svc_123"}'CLI equivalent
There's no working CLI shell yet — openship service exec is a stub that prints "coming soon" (the CLI
ships no WebSocket client). Use the dashboard's service Terminal tab, which drives these endpoints.
Open the WebSocket
GET /api/services/terminal/ws/:serviceIdConnect 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
Originmust be in the instance's trusted-origins allowlist, or the socket closes with4403. - Identity — pass the ticket from
/ticketas a WebSocket subprotocol, prefixed withopenship.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 withopenship.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: https://your-host"Errors you might see
The WebSocket signals failures by sending an {"type":"error"} frame and then closing with a specific code:
4401 — unauthorized
No valid ticket or session, no active organization, or the ticket's service doesn't match the path
:serviceId. Mint a fresh ticket (they're single-use and short-lived) and connect immediately.
4404 — service not found or not deployed
The service isn't in your active organization, you lack admin on its project, or it has no running container yet (still deploying, or the project has no active deployment). List services with the Services API to confirm it's live.
4400 — terminal not supported
The service's runtime doesn't offer an interactive shell (not_supported), or the :serviceId was missing.
4429 — too many sessions
You've hit the per-user concurrent-session cap. Close an existing terminal and retry.
4403 — origin not allowed
The request Origin isn't in the trusted-origins allowlist. Connect from the dashboard's own host.