Terminal

The terminal endpoint hands you a real Linux PTY inside the sandbox over a WebSocket. It's what powers the dashboard's "Connect" tab, and it's the right primitive to embed if you're building an IDE, a CI live-tail, or a pair-debugging tool.

Two flavors:

Both endpoints upgrade an Authorization: Bearer … HTTP GET to a WebSocket.

Single-user PTY

GET /v1/sandboxes/{id}/exec/pty?rows=40&cols=120
Upgrade: websocket

Wire protocol after the upgrade:

The shell defaults to bash -li (login + interactive). Override with ?cmd= (URL-encoded full command line) when you want a single program: ?cmd=htop, ?cmd=python3, etc.

Browser example (xterm.js)

import { Terminal } from "@xterm/xterm";

const ws = new WebSocket(
  `wss://api.pandastack.ai/v1/sandboxes/${id}/exec/pty?rows=40&cols=120`,
  ["pds-pty", `bearer.${token}`],   // subprotocol-based auth for browsers
);
ws.binaryType = "arraybuffer";

const term = new Terminal({ rows: 40, cols: 120 });
term.open(document.getElementById("term")!);

ws.onmessage = (ev) => {
  if (typeof ev.data === "string") {
    const msg = JSON.parse(ev.data);
    if (msg.type === "exit") term.write(`\r\n[process exited ${msg.code}]\r\n`);
  } else {
    term.write(new Uint8Array(ev.data));
  }
};

term.onData((data) => ws.send(new TextEncoder().encode(data)));
term.onResize(({ rows, cols }) => ws.send(JSON.stringify({ type: "resize", rows, cols })));

CLI

pandastack sandbox shell <sandbox-id>           # opens a PTY in your terminal
pandastack sandbox shell <sandbox-id> -- htop   # one-off command

Shared PTY (multiplayer)

/exec/pty/shared is the multiplayer terminal — many viewers around one shell. The first connection opens the PTY and becomes the stdin holder; subsequent connections only see output until they ask for the keyboard.

GET /v1/sandboxes/{id}/exec/pty/shared?name=alice&rows=40&cols=120
Upgrade: websocket

Extra messages on top of the single-user protocol:

Lifecycle:

1. First subscriber opens the PTY and is auto-promoted to holder.
2. Holder leaves → holder = ""; the next request_stdin claims it.
3. PTY's underlying shell exits → server broadcasts {exit, code} and closes every connection.

This is exactly the multiplayer primitive the dashboard ships — see Multiplayer for the higher-level CRDT / cursor sync that rides alongside it.

Use cases

Developer tool: in-browser shell. A "Connect" button in your app opens a tab with a full bash shell into the user's sandbox. xterm.js + 30 lines of WS glue.

Agent watcher. Your agent runs pytest -x via exec. You drop a teammate into the same shared PTY with read-only viewer privileges so they can watch in real time without yanking the keyboard.

Human-in-the-loop confirmation. The agent runs a git push that prompts for a passphrase. The dashboard pops "an interactive prompt is waiting" — a human takes over stdin for a moment, types the secret, hands it back.

Classroom / pair programming. Instructor opens the shared PTY, several students join, one student is granted stdin to attempt an exercise, others watch.

Limits

• One PTY per sandbox per shared-hub. Multiple ?cmd= shells need separate /exec/pty connections.
• Idle disconnect after 10 minutes of no traffic in either direction (keep-alive with an empty resize at least every 5 min if needed).
• Default capacity: 64 viewers per shared PTY. Past that, new connections get 1013 Try Again Later.