> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensorlake.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Attach PTY WebSocket

> Upgrade to a WebSocket connection for an interactive PTY session.

Attach to a PTY session over WebSocket.

## Endpoint

```http theme={null}
GET /api/v1/pty/{session_id}/ws
```

Use the WebSocket endpoint on the sandbox proxy host:

```text theme={null}
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](/api-reference/v2/pty/create).

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.

For an end-to-end example that creates the session, sends `READY`, runs a command, reads output, and closes cleanly, see [PTY Sessions](/sandboxes/pty-sessions).

### Client-to-server opcodes

| Opcode | Meaning | Payload                                                     |
| ------ | ------- | ----------------------------------------------------------- |
| `0x00` | Data    | Raw terminal input bytes                                    |
| `0x01` | Resize  | `cols` as big-endian `u16`, then `rows` as big-endian `u16` |
| `0x02` | Ready   | No payload                                                  |

### Server-to-client opcodes

| Opcode | Meaning | Payload                       |
| ------ | ------- | ----------------------------- |
| `0x00` | Data    | Raw terminal output bytes     |
| `0x03` | Exit    | Exit code as big-endian `i32` |

## Example Connection

Header-based token:

```bash theme={null}
wscat -H "X-PTY-Token: <token>" -c "wss://<sandbox-id>.sandbox.tensorlake.ai/api/v1/pty/<session-id>/ws"
```

Query-string token:

```bash theme={null}
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.


## OpenAPI

````yaml get /api/v1/pty/{session_id}/ws
openapi: 3.1.0
info:
  title: Tensorlake API
  description: >-
    Tensorlake Cloud APIs for Sandboxes, Document Ingestion, and Serverless
    Workflows
  license:
    name: ''
  version: 0.1.0
servers:
  - url: https://api.tensorlake.ai/
security:
  - bearerAuth: []
tags:
  - name: Tensorlake Cloud API
    description: >-
      Tensorlake Cloud APIs for Sandboxes, Document Ingestion, and Serverless
      Workflows
paths:
  /api/v1/pty/{session_id}/ws:
    servers:
      - url: wss://{identifier}.sandbox.tensorlake.ai
        description: >-
          Example sandbox proxy WebSocket host for a specific running sandbox.
          For programmatic access, use the sandbox's `ingress_endpoint`.
        variables:
          identifier:
            default: example-sandbox
            description: The sandbox ID or sandbox name.
    parameters:
      - name: session_id
        in: path
        description: The PTY session identifier.
        required: true
        schema:
          type: string
      - name: token
        in: query
        description: >-
          Optional PTY token. Prefer the `X-PTY-Token` header instead of the
          query string.
        required: false
        schema:
          type: string
      - name: X-PTY-Token
        in: header
        description: Preferred PTY session token header for WebSocket authentication.
        required: false
        schema:
          type: string
    get:
      tags:
        - sandbox-pty
      summary: Attach to a PTY session over WebSocket
      description: Upgrade to a WebSocket connection for an interactive PTY session.
      operationId: sandbox_pty_websocket
      responses:
        '101':
          description: WebSocket upgrade successful
        '403':
          description: Invalid PTY token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxProxyError'
        '404':
          description: PTY session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxProxyError'
components:
  schemas:
    SandboxProxyError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
        code:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````