PTY Sessions

Use PTY sessions when you need an interactive shell, REPL, or TUI inside a running sandbox. The session is created over HTTPS, but terminal input and output move over a WebSocket attached to that session.

The PTY management endpoints live on the sandbox proxy host, not https://api.tensorlake.ai:https://<sandbox-id-or-name>.sandbox.tensorlake.aiCreate, list, get, resize, and kill requests require Authorization: Bearer $TENSORLAKE_API_KEY. The WebSocket attach step also requires the per-session PTY token returned from session creation.

Happy Path

Call createPty() or create_pty() on a connected sandbox client.
Tensorlake creates the PTY session, opens the WebSocket, and sends the initial READY frame for you.
Use the returned handle to send input, resize the terminal, stream output, wait for exit, disconnect, reconnect, or kill the session.
If you need to reattach later, call connectPty() or connect_pty() with the original sessionId and token.

High-Level SDK API

The connected sandbox client now exposes a high-level PTY handle instead of making you manage WebSocket framing yourself. The handle exposes:

sendInput() / send_input() to write terminal input
resize() to change rows and columns
wait() to block until the PTY exits and get the exit code
disconnect() to close the current WebSocket without killing the PTY
connect() to reattach the same handle later
kill() to terminate the PTY session over HTTP
onData() / on_data() and onExit() / on_exit() to subscribe to output and exit events

CLI
Python
TypeScript

Use tl sbx ssh when you want an interactive terminal immediately and do not need to manage PTY sessions programmatically:

tl sbx ssh my-sandbox

tl sbx ssh my-sandbox --shell /bin/sh

tl sbx ssh uses the PTY API under the hood and requires an interactive terminal. For reconnectable sessions or application-managed PTY control, use the Python or TypeScript SDK.

from tensorlake.sandbox import SandboxClient

client = SandboxClient()

with client.create_and_connect() as sandbox_client:
    pty = sandbox_client.create_pty(
        command="/bin/bash",
        args=["-l"],
        env={"TERM": "xterm-256color"},
        working_dir="/workspace",
        cols=80,
        rows=24,
    )

    pty.on_data(lambda data: print(data.decode("utf-8"), end=""))
    pty.on_exit(lambda code: print(f"\nExited: {code}"))

    pty.send_input("printf 'hello from PTY\\n'; pwd\\n")
    pty.resize(120, 40)
    pty.send_input("exit\n")

    exit_code = pty.wait()
    print(f"Final exit code: {exit_code}")

To reconnect later:

pty = sandbox_client.connect_pty(session_id, token)

import { SandboxClient } from "tensorlake";

const client = SandboxClient.forCloud({
  apiKey: process.env.TENSORLAKE_API_KEY,
});
const sandboxClient = await client.createAndConnect();

try {
  const pty = await sandboxClient.createPty({
    command: "/bin/bash",
    args: ["-l"],
    env: { TERM: "xterm-256color" },
    workingDir: "/workspace",
    cols: 80,
    rows: 24,
    onData: (data) => process.stdout.write(Buffer.from(data)),
    onExit: (exitCode) => console.log("Exited:", exitCode),
  });

  await pty.sendInput("printf 'hello from PTY\\n'; pwd\\n");
  await pty.resize(120, 40);
  await pty.sendInput("exit\\n");

  const exitCode = await pty.wait();
  console.log("Final exit code:", exitCode);
} finally {
  await sandboxClient.terminate();
  client.close();
}

To reconnect later, keep pty.sessionId and pty.token and call:

const pty = await sandboxClient.connectPty(sessionId, token, {
  onData: (data) => process.stdout.write(Buffer.from(data)),
});

createPty() / create_pty() already open the WebSocket and send READY. Use connectPty() / connect_pty() only when you are reattaching to an existing session.

Raw HTTP and WebSocket Flow

The raw protocol is small enough that you can drive it yourself from any HTTP client plus any WebSocket client. These calls assume you already have a running sandbox ID or sandbox name.

1. Create the PTY session

curl -sS -X POST https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/pty \
  -H "Authorization: Bearer $TENSORLAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "/bin/bash",
    "args": ["-l"],
    "env": {"TERM": "xterm-256color"},
    "working_dir": "/workspace",
    "rows": 24,
    "cols": 80
  }'

Response:

{
  "session_id": "LYtJOrxE9Kz3bphPUDzuX",
  "token": "<pty-session-token>"
}

2. Attach the WebSocket

Open this URL:

wss://<sandbox-id>.sandbox.tensorlake.ai/api/v1/pty/<session-id>/ws

Send the PTY token on the upgrade request:

X-PTY-Token: <pty-session-token>

If your client cannot set headers, append ?token=<pty-session-token> to the WebSocket URL instead.

3. Exchange PTY frames

Direction	Bytes	Meaning
Client -> server	`02`	`READY`: flush any buffered output
Client -> server	`00` + UTF-8 bytes	Send terminal input
Client -> server	`01` + `cols` + `rows`	Resize terminal, with `cols` then `rows` as big-endian `u16`
Server -> client	`00` + raw bytes	Terminal output
Server -> client	`03` + 4-byte big-endian signed int	Process exit code

Common examples:

Action	Bytes
Send `READY`	`02`
Run `pwd\n`	`00 70 77 64 0a`
Run `exit\n`	`00 65 78 69 74 0a`
Exit code `0`	`03 00 00 00 00`
Resize to 120x40	`01 00 78 00 28`

4. Close or abort

To close cleanly, write exit\n to the shell and wait for the 0x03 exit frame followed by the normal WebSocket close. To terminate the session immediately:

curl -X DELETE https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/pty/<session-id> \
  -H "Authorization: Bearer $TENSORLAKE_API_KEY"

Notes

createPty() / create_pty() send READY for you immediately after the socket opens.
Closing the WebSocket does not kill the PTY session. You can reconnect while the shell is still running.
Persist the original PTY token if you plan to reconnect. Get PTY Session and List PTY Sessions do not return it again.
PTY sessions with no connected clients are killed after 300 seconds of inactivity.
You can resize either with the 0x01 WebSocket frame or with Resize PTY Session.
For the endpoint-by-endpoint API reference, see PTY Sessions API.

Overview

Guides

Use Cases

Happy Path

High-Level SDK API

Raw HTTP and WebSocket Flow

1. Create the PTY session

2. Attach the WebSocket

3. Exchange PTY frames

4. Close or abort

Notes

Overview

Guides

Use Cases

​Happy Path

​High-Level SDK API

​Raw HTTP and WebSocket Flow

​1. Create the PTY session

​2. Attach the WebSocket

​3. Exchange PTY frames

​4. Close or abort

​Notes

Happy Path

High-Level SDK API

Raw HTTP and WebSocket Flow

1. Create the PTY session

2. Attach the WebSocket

3. Exchange PTY frames

4. Close or abort

Notes