Add PTY terminal passthrough for browser clients

[whoiskatrin]

Summary

Enables browser-based terminal UIs to connect to sandbox shells via WebSocket. The terminal() method proxies WebSocket connections to the container's PTY, with output buffering for replay on reconnect.

What's included

• sandbox.terminal(request) — proxy a WebSocket upgrade to a container PTY.
• Multiple terminals per sandbox — each session can have its own terminal with isolated working directory and environment, so users can run separate shells side-by-side in the same container.
• @cloudflare/sandbox/xterm — SandboxAddon for xterm.js with automatic reconnection (exponential backoff + jitter), buffered output replay, and resize forwarding.

Usage

// Worker: proxy WebSocket to container terminal
return sandbox.terminal(request, { cols: 80, rows: 24 });

// Multiple isolated terminals in the same sandbox
const dev = await sandbox.getSession('dev');
return dev.terminal(request);

// Browser: xterm.js addon
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' });

[changeset-bot]

🦋 Changeset detected

Latest commit: 9f6d732

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@cloudflare/sandbox	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/sandbox-sdk/@cloudflare/sandbox@310

commit: bfd0fc2

[github-actions]

🐳 Docker Images Published

Default:

FROM cloudflare/sandbox:0.0.0-pr-310-a012aaf

With Python:

FROM cloudflare/sandbox:0.0.0-pr-310-a012aaf-python

With OpenCode:

FROM cloudflare/sandbox:0.0.0-pr-310-a012aaf-opencode

Version: 0.0.0-pr-310-a012aaf

Use the -python variant if you need Python code execution, or -opencode for the variant with OpenCode AI coding agent pre-installed.

---

📦 Standalone Binary

For arbitrary Dockerfiles:

COPY --from=cloudflare/sandbox:0.0.0-pr-310-a012aaf /container-server/sandbox /sandbox
ENTRYPOINT ["/sandbox"]

Download via GitHub CLI:

gh run download 21754460919 -n sandbox-binary

Extract from Docker:

docker run --rm cloudflare/sandbox:0.0.0-pr-310-a012aaf cat /container-server/sandbox > sandbox && chmod +x sandbox

[github-actions]

OpenCode Review

This PR adds comprehensive PTY terminal support for browser-based terminal UIs. The implementation is well-structured across the three-layer architecture, adding WebSocket passthrough from the SDK to container-side PTY management.

Architecture Assessment

Layer separation is clean: PTY handling is properly distributed - WebSocket routing in the server layer, business logic in SessionManager, and SDK integration via proxy methods. The use of Bun's Terminal API is appropriate for the container runtime.

Code Quality

Strong error handling: The PTY WebSocket handler has proper connection lifecycle management, graceful error responses, and cleanup on disconnection. Error propagation through status messages is well designed.

Memory management: ByteRingBuffer implementation for output buffering is solid - handles wrap-around correctly and provides proper capacity management for terminal history replay.

Implementation Concerns

Container dependency injection: Adding PtyWebSocketHandler to the DI container follows established patterns and integrates properly with SessionManager.

Session mutex interaction: PTY creation correctly uses the session mutex via getPty() in SessionManager, maintaining consistency with command execution serialization model described in the concurrency docs.

WebSocket connection discrimination: The server properly discriminates between control plane WebSockets (type: 'control') and PTY WebSockets (type: 'pty') in the unified handler.

Missing Elements

Browser E2E tests: The package.json shows test:e2e:browser using Playwright, but no browser test files are visible. For a terminal feature, automated browser testing would verify WebSocket connectivity, xterm.js integration, and terminal interaction flows.

Testing coverage: While unit tests would be expected for the ring buffer and PTY classes, no test files are visible for the new PTY functionality. Terminal features benefit from integration tests covering reconnection, output buffering, and resize events.

SDK Integration

getSandbox proxy pattern: The proxy approach in getSandbox() to intercept session-returning methods and enhance them with terminal() is clever. It preserves RPC behavior while adding client-side WebSocket capabilities.

Type safety: The PTY types in shared package are properly exported and used consistently across layers.

Looks good to merge once browser testing is in place to verify the complete terminal experience.

[github-actions]

OpenCode Review

Strong implementation of PTY terminal passthrough functionality. The architecture cleanly separates concerns with WebSocket transport handled at the DO layer and PTY management in the container. The xterm.js addon provides solid client-side handling with proper reconnection.

Key Strengths

Layered Architecture: The separation between WebSocket transport (DO level) and PTY management (container level) is well designed. The proxyTerminal() function elegantly bridges the two layers.

Client Reliability: The SandboxAddon implements proper exponential backoff + jitter reconnection, buffered output replay, and handles both binary (terminal data) and JSON (control messages) protocols correctly.

Type Safety: New PtyOptions and PtyStatusMessage types are properly shared between layers and the export structure maintains clean separation between main SDK and xterm-specific functionality.

Areas for Improvement

Container Changes Missing from Review: The PR adds container-side PTY handling (pty-ws-handler.ts) but I don't see the core Pty class implementation or session manager integration. Are these changes in a separate file that should be included?

Buffer Management: The buffered output replay in SandboxAddon clears the terminal only if no buffer was received, but what happens with very large buffers that might exceed WebSocket message limits?

Error Propagation: Control message errors in the container (handleControl) are logged but only generic "Invalid control message" is sent to clients. More specific error types would help debugging.

Looks good to merge once container implementation is confirmed complete.

[github-actions]

Silent ignore of non-JSON strings could hide protocol issues. Consider logging malformed messages at debug level for troubleshooting.

[github-actions]

This error message could be more specific. Consider: 'terminal() requires WebSocket upgrade header: expected "websocket", got "..."}'