Interactive browser terminals in Sandboxes
The Sandbox SDK ↗ now supports PTY (pseudo-terminal) passthrough, enabling browser-based terminal UIs to connect to sandbox shells via WebSocket.
The new terminal() method proxies a WebSocket upgrade to the container's PTY endpoint, with output buffering for replay on reconnect.
// Worker: proxy WebSocket to container terminalreturn sandbox.terminal(request, { cols: 80, rows: 24 });// Worker: proxy WebSocket to container terminalreturn sandbox.terminal(request, { cols: 80, rows: 24 });Each session can have its own terminal with an isolated working directory and environment, so users can run separate shells side-by-side in the same container.
// Multiple isolated terminals in the same sandboxconst dev = await sandbox.getSession("dev");return dev.terminal(request);// Multiple isolated terminals in the same sandboxconst dev = await sandbox.getSession("dev");return dev.terminal(request);The new @cloudflare/sandbox/xterm export provides a SandboxAddon for xterm.js ↗ with automatic reconnection (exponential backoff + jitter), buffered output replay, and resize forwarding.
import { SandboxAddon } from "@cloudflare/sandbox/xterm";
const addon = new SandboxAddon({ getWebSocketUrl: ({ sandboxId, origin }) => `${origin}/ws/terminal?id=${sandboxId}`, onStateChange: (state, error) => updateUI(state),});terminal.loadAddon(addon);addon.connect({ sandboxId: "my-sandbox" });import { SandboxAddon } from "@cloudflare/sandbox/xterm";
const addon = new SandboxAddon({ getWebSocketUrl: ({ sandboxId, origin }) => `${origin}/ws/terminal?id=${sandboxId}`, onStateChange: (state, error) => updateUI(state),});terminal.loadAddon(addon);addon.connect({ sandboxId: "my-sandbox" });To update to the latest version:
npm i @cloudflare/sandbox@latest