Skip to main content
GET
/
api
/
v1
/
pty
/
{session_id}
/
ws
Attach to a PTY session over WebSocket
curl --request GET \
  --url wss://{sandbox_id_or_name}.sandbox.tensorlake.ai/api/v1/pty/{session_id}/ws \
  --header 'Authorization: Bearer <token>'
{
  "error": "<string>",
  "code": "<string>"
}
Attach to a PTY session over WebSocket.

​
Endpoint

GET /api/v1/pty/{session_id}/ws
Use the WebSocket endpoint on the sandbox proxy host: 
wss://<sandbox-id-or-name>.sandbox.tensorlake.ai/api/v1/pty/<session-id>/ws

​
Authentication

You must provide the PTY token returned from Create PTY Session. Tensorlake accepts the token in either place:
  • Preferred: X-PTY-Token: <token>
  • Backward-compatible fallback: ?token=<token>
The header form is preferred because query parameters are more likely to appear in access logs.

​
WebSocket Protocol

After connecting, send a binary READY frame immediately so Tensorlake can flush any buffered output.

​
Client-to-server opcodes

OpcodeMeaningPayload
0x00DataRaw terminal input bytes
0x01Resizecols as big-endian u16, then rows as big-endian u16
0x02ReadyNo payload

​
Server-to-client opcodes

OpcodeMeaningPayload
0x00DataRaw terminal output bytes
0x03ExitExit code as big-endian i32

​
Example Connection

Header-based token: 
wscat -H "X-PTY-Token: <token>" -c "wss://<sandbox-id>.sandbox.tensorlake.ai/api/v1/pty/<session-id>/ws"
Query-string token: 
wscat -c "wss://<sandbox-id>.sandbox.tensorlake.ai/api/v1/pty/<session-id>/ws?token=<token>"

​
Connection Semantics

  • If the token is invalid, Tensorlake returns 403 Forbidden with code INVALID_TOKEN.
  • If the session does not exist, Tensorlake returns 404 Not Found with code SESSION_NOT_FOUND.
  • When the process exits, Tensorlake sends the 0x03 exit frame and then closes the WebSocket with reason exit:<code>.
  • If the PTY session is terminated while the socket is open, Tensorlake closes the WebSocket with code 1001 and reason session terminated.
  • If you do not send READY, Tensorlake buffers output up to 1 MB before disconnecting the client.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
X-PTY-Token
string

Preferred PTY session token header for WebSocket authentication.

Path Parameters

​
session_id
string
required

The PTY session identifier.

Query Parameters

​
token
string

Optional PTY token. Prefer the X-PTY-Token header instead of the query string.

Response

WebSocket upgrade successful