> ## 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.

# TCP Tunnel WebSocket

> Upgrade to a WebSocket that relays binary frames to and from a sandbox-local TCP port.

Open an authenticated WebSocket tunnel to a TCP port listening inside the sandbox.

Use this endpoint when you need raw TCP byte forwarding, such as VNC, Postgres, Redis, or Chrome DevTools over a private local tunnel. For most users, the `tl sbx tunnel` CLI or SDK helper manages this protocol for you.

## Endpoint

```http theme={null}
GET /api/v1/tunnels/tcp?port=<remote-port>
```

Use the WebSocket endpoint on the sandbox proxy host:

```text theme={null}
wss://<sandbox-id-or-name>.sandbox.tensorlake.ai/api/v1/tunnels/tcp?port=9222
```

## Example Connection

Authenticate to the sandbox proxy with your API key. The proxy injects the internal forwarded-auth headers that the daemon requires.

```bash theme={null}
wscat -c "wss://<sandbox-id>.sandbox.tensorlake.ai/api/v1/tunnels/tcp?port=9222" \
  -H "Authorization: Bearer $TENSORLAKE_API_KEY"
```

## WebSocket Protocol

After the WebSocket upgrade succeeds, binary frames are relayed verbatim:

* Client binary frames are written to `127.0.0.1:<port>` inside the sandbox.
* Bytes read from that TCP connection are sent back as WebSocket binary frames.
* Text frames are rejected.

## Response Semantics

* `101 Switching Protocols` means the tunnel is open.
* `400 Bad Request` means `port` is missing, invalid, or `0`.
* `401 Unauthorized` means authenticated sandbox-proxy forwarding was not present.
* `502 Bad Gateway` means nothing accepted the TCP connection on `127.0.0.1:<port>` inside the sandbox.

For local-port forwarding examples, see [Local Tunnels](/sandboxes/tunnels).


## OpenAPI

````yaml get /api/v1/tunnels/tcp
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/tunnels/tcp:
    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: port
        in: query
        description: Sandbox-local TCP port to connect to on 127.0.0.1.
        required: true
        schema:
          type: integer
          minimum: 1
          maximum: 65535
    get:
      tags:
        - sandbox-tunnels
      summary: Open a TCP tunnel WebSocket
      description: >-
        Upgrade to a WebSocket that relays binary frames to and from a
        sandbox-local TCP port.
      operationId: sandbox_tcp_tunnel
      responses:
        '101':
          description: WebSocket upgrade successful
        '400':
          description: Missing or invalid port
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxProxyError'
        '401':
          description: Authenticated sandbox-proxy forwarding is required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxProxyError'
        '502':
          description: >-
            The TCP target inside the sandbox refused the connection or was not
            listening
          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

````