Skip to content

Add PTY terminal passthrough for browser clients#27252

Merged
ghostwriternr merged 8 commits intoproductionfrom
sync-docs-pr-310
Feb 9, 2026
Merged

Add PTY terminal passthrough for browser clients#27252
ghostwriternr merged 8 commits intoproductionfrom
sync-docs-pr-310

Conversation

@agents-git-bot
Copy link
Contributor

@agents-git-bot agents-git-bot bot commented Dec 19, 2025 •
edited
Loading

Summary

Documents the new terminal support feature that enables browser-based terminal UIs to connect to sandbox shells via WebSocket. This change corresponds to PR #310 in cloudflare/sandbox-sdk.

What's included

  • Terminal API reference - Documents sandbox.terminal() and session.terminal() methods for WebSocket proxy connections
  • xterm.js Addon reference - Complete API documentation for the SandboxAddon class that handles browser-side connections
  • Browser terminal integration guide - Step-by-step how-to guide for building interactive terminal UIs with automatic reconnection, output buffering, and multi-session support

Changes

  • Added /sandbox/api/terminal/ - API reference for terminal WebSocket methods
  • Added /sandbox/api/xterm-addon/ - Documentation for the browser-side xterm.js addon
  • Added /sandbox/guides/browser-terminals/ - Complete integration guide with examples
  • Updated /sandbox/api/ index to include new terminal API sections
  • Updated /sandbox/api/sessions/ to reference terminal methods

Features documented

  • WebSocket-based terminal connections from browser to sandbox shells
  • Multiple isolated terminals per sandbox with session-based isolation
  • Automatic reconnection with exponential backoff and jitter
  • Buffered output replay for seamless reconnection
  • Shell state persistence (working directory, environment, history)
  • Complete xterm.js integration with TypeScript support

Synced from: cloudflare/sandbox-sdk#310

@github-actions
Copy link
Contributor

github-actions bot commented Dec 19, 2025 •
edited
Loading

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern Owners
/src/content/docs/sandbox/ @elithrar, @whoiskatrin, @ghostwriternr, @cloudflare/pcx-technical-writing, @cloudflare/ai-agents, @cloudflare/dev-plat-leads

@agents-git-bot
Copy link
Contributor Author

agents-git-bot bot commented Dec 19, 2025

Updated with comprehensive PTY API documentation:

  • Complete API reference for all pty methods (create(), attach(), getById(), list())
  • PTY handle methods documentation (write(), resize(), kill(), onData(), onExit(), close())
  • Async iteration support examples
  • Use case examples: interactive shells, language REPLs, automated terminal sessions
  • Transport considerations (HTTP vs WebSocket)
  • Updated API index with PTY card

Ready for review.

@agents-git-bot
Copy link
Contributor Author

agents-git-bot bot commented Dec 19, 2025

Updated documentation with comprehensive PTY coverage:

Added Files

  • API Reference (src/content/docs/sandbox/api/pty.mdx): Complete PTY API documentation with all methods, parameters, and examples
  • How-to Guide (src/content/docs/sandbox/guides/interactive-terminals.mdx): Practical guide for building interactive terminal applications
  • API Index Update: Added PTY card to API navigation

Documentation Highlights

  • Clear distinction between PTY and Commands API use cases
  • Complete method documentation with TypeScript examples
  • Real-world use cases (interactive shells, text editors, Python REPL)
  • Control character handling and terminal resizing
  • Session attachment patterns
  • Error handling and best practices

All content follows Cloudflare docs style guide with TypeScriptExample components and proper linking.

🤖 Generated with Claude Code

@github-actions
Copy link
Contributor

github-actions bot commented Dec 19, 2025 •
edited
Loading

Preview URL: https://d5eea3bb.preview.developers.cloudflare.com
Preview Branch URL: https://sync-docs-pr-310.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link Updated Link
https://developers.cloudflare.com/sandbox/ https://sync-docs-pr-310.preview.developers.cloudflare.com/sandbox/
https://developers.cloudflare.com/sandbox/api/terminal/ https://sync-docs-pr-310.preview.developers.cloudflare.com/sandbox/api/terminal/
https://developers.cloudflare.com/sandbox/guides/browser-terminals/ https://sync-docs-pr-310.preview.developers.cloudflare.com/sandbox/guides/browser-terminals/
https://developers.cloudflare.com/sandbox/concepts/terminal/ https://sync-docs-pr-310.preview.developers.cloudflare.com/sandbox/concepts/terminal/
https://developers.cloudflare.com/sandbox/api/ https://sync-docs-pr-310.preview.developers.cloudflare.com/sandbox/api/
https://developers.cloudflare.com/sandbox/api/sessions/ https://sync-docs-pr-310.preview.developers.cloudflare.com/sandbox/api/sessions/
https://developers.cloudflare.com/sandbox/guides/websocket-connections/ https://sync-docs-pr-310.preview.developers.cloudflare.com/sandbox/guides/websocket-connections/
https://developers.cloudflare.com/sandbox/concepts/ https://sync-docs-pr-310.preview.developers.cloudflare.com/sandbox/concepts/

@agents-git-bot agents-git-bot bot changed the title Sync docs from cloudflare/sandbox-sdk PR #310: add PTY support add PTY support Dec 19, 2025
@agents-git-bot agents-git-bot bot changed the title add PTY support Add PTY (pseudo-terminal) API documentation Dec 21, 2025
@agents-git-bot agents-git-bot bot force-pushed the sync-docs-pr-310 branch 2 times, most recently from a246615 to 7eb6adf Compare December 22, 2025 14:55
@agents-git-bot agents-git-bot bot changed the title Add PTY (pseudo-terminal) API documentation Add PTY (pseudo-terminal) documentation Dec 22, 2025
@agents-git-bot
Copy link
Contributor Author

agents-git-bot bot commented Dec 22, 2025

Updated with complete documentation:

  • Rewrote API reference with comprehensive coverage of all PTY methods and properties
  • Added detailed how-to guide with practical examples including web terminal implementation, xterm.js integration, and interactive automation patterns
  • Ensured compliance with Cloudflare style guide (TypeScriptExample components, proper links, no contractions)
  • Added cross-links to related documentation

Ready for review!

@agents-git-bot agents-git-bot bot changed the title Add PTY (pseudo-terminal) documentation Add PTY (pseudo-terminal) API documentation Dec 22, 2025
@agents-git-bot agents-git-bot bot force-pushed the sync-docs-pr-310 branch 2 times, most recently from 683febe to 58b0d0d Compare December 23, 2025 11:11
@agents-git-bot agents-git-bot bot changed the title Add PTY (pseudo-terminal) API documentation Add PTY (pseudo-terminal) documentation Dec 23, 2025
@agents-git-bot agents-git-bot bot force-pushed the sync-docs-pr-310 branch 2 times, most recently from 9d7acc2 to d0cdd01 Compare December 23, 2025 14:53
@agents-git-bot agents-git-bot bot changed the title Add PTY (Pseudo-Terminal) Documentation Add PTY (pseudo-terminal) support documentation Jan 8, 2026
@agents-git-bot
Copy link
Contributor Author

agents-git-bot bot commented Jan 8, 2026

Update: Added Terminal Emulation Guide

I've added a comprehensive how-to guide for terminal emulation to complement the existing PTY API reference:

New file: src/content/docs/sandbox/guides/terminal-emulation.mdx

Coverage:

  • When to use PTY vs exec() for different scenarios
  • Integration with xterm.js for web-based terminals
  • WebSocket handler implementation patterns
  • ANSI escape sequences and terminal control
  • Running interactive applications (Python REPL, vim, etc.)
  • Collaborative terminal pattern for multi-user sessions
  • Session reconnection handling
  • Best practices for PTY management

This guide provides practical examples for developers building terminal interfaces, complementing the API reference with real-world implementation patterns.

Related to cloudflare/sandbox-sdk#310

@agents-git-bot agents-git-bot bot changed the title Add PTY (pseudo-terminal) support documentation add PTY support Jan 9, 2026
@agents-git-bot agents-git-bot bot changed the title add PTY support Sync docs from cloudflare/sandbox-sdk#310: add PTY support Jan 9, 2026
@agents-git-bot agents-git-bot bot force-pushed the sync-docs-pr-310 branch 2 times, most recently from 0d60176 to 883f22c Compare January 20, 2026 16:46
@asmaylsydbdalzym808-sketch

This comment was marked as spam.

Sign in to view
@github-actions
Add terminal/PTY support documentation
e4ea4b9 
- Add comprehensive terminal API reference with WebSocket protocol details
- Create detailed guide for building browser-based terminal UIs
- Include xterm.js SandboxAddon integration and examples
- Document multi-session terminal support and error handling
- Add terminal feature showcase to main sandbox overview
- Update API index to include new terminal functionality

Covers the new terminal() method, proxyTerminal() function, and
@cloudflare/sandbox/xterm addon introduced in PR #310.
@agents-git-bot agents-git-bot bot changed the title Sync docs from cloudflare/sandbox-sdk#310: add PTY support Add PTY terminal passthrough for browser clients Feb 6, 2026
@github-actions
Add terminal API documentation for browser integration
edcf64d 
Documents the new terminal() methods that enable WebSocket-based
browser terminals connected to sandbox shells, including the xterm.js
addon and complete integration guide.
@ghostwriternr
Copy link
Member

ghostwriternr commented Feb 9, 2026

/bonk fix the conflict and ensure build is passing

opencode-agent bot and others added 3 commits February 9, 2026 14:20
@ask-bonk
Copy link
Contributor

ask-bonk bot commented Feb 9, 2026

Here's a summary of what was done:

Changes Made

1. Resolved merge conflict with production

File: src/content/docs/sandbox/index.mdx

The branch had a conflict where the PR's "Terminal Access" tab had replaced the "File Watching" tab that was added to production. Resolved by keeping both tabs - the existing "File Watching" tab from production and the new "Terminal Access" tab from this PR.

2. Fixed build error in browser-terminals.mdx

File: src/content/docs/sandbox/guides/browser-terminals.mdx

An HTML code block (<!DOCTYPE html>...) was wrapped in a <TypeScriptExample> component, which attempts to parse its contents as TypeScript/JavaScript via prettier's babel parser. This caused the build to fail with Unexpected token (1:1). Fixed by removing the <TypeScriptExample> wrapper and using a plain fenced html code block instead.

3. Added ts language identifiers to code fences

Files: src/content/docs/sandbox/api/terminal.mdx (6 fixes), src/content/docs/sandbox/api/xterm-addon.mdx (7 fixes)

All code blocks inside <TypeScriptExample> components were using bare triple backticks without a language identifier. Added ts to ensure proper syntax highlighting in both the TypeScript and auto-generated JavaScript tabs.

Commits

  1. b978f4e - Merge production into sync-docs-pr-310 and resolve sandbox index conflict
  2. c4cec65 - Fix build errors: remove HTML from TypeScriptExample wrapper and add ts language identifiers to code fences

github run

@ask-bonk ask-bonk bot requested a review from elithrar as a code owner February 9, 2026 14:50
@ghostwriternr ghostwriternr enabled auto-merge (squash) February 9, 2026 19:33
@ghostwriternr
Copy link
Member

ghostwriternr commented Feb 9, 2026

/bonk can you kickoff the pending action here? Seems stuck for no reason

@opencode-agent
[Sandbox] Fix MDX syntax errors and add missing code fence language i…
d5eea3b 
…dentifiers

- Remove stray code fences at end of sessions.mdx and index.mdx
- Fix four-backtick code fence in terminal.mdx (should be three)
- Add ts language identifiers to all TypeScriptExample code blocks
- Add txt language to ASCII diagram in concepts/terminal.mdx
- Remove invalid top-level order:0 from index.mdx frontmatter
@ask-bonk
Copy link
Contributor

ask-bonk bot commented Feb 9, 2026

Here's what I found and fixed:

Summary

The CI was actually passing on the latest commit — the previous /bonk run from Feb 9 successfully resolved the merge conflict and fixed build errors. The CI workflow completed successfully but its check-runs weren't surfacing on the PR's commit status (only CodeQL checks were visible), which made it look stuck.

However, I found several additional issues in the PR files that could cause build failures or rendering problems:

Critical fixes

  1. sessions.mdx — Stray ``` code fence at end of file after the "Related resources" section
  2. terminal.mdx — Four backticks ( ````) instead of three closing a <TypeScriptExample> code block (line 50)
  3. index.mdx — Stray ``` code fence at end of file after </CardGrid>

Other fixes

  1. sessions.mdx, terminal.mdx, browser-terminals.mdx — Added ts language identifiers to all 10 code blocks inside <TypeScriptExample> components that were using bare ```
  2. concepts/terminal.mdx — Added txt language to ASCII diagram code block
  3. index.mdx — Removed invalid top-level order: 0 from frontmatter (only sidebar.order is valid)

github run

@ghostwriternr ghostwriternr merged commit f4dceb9 into production Feb 9, 2026
9 checks passed
@ghostwriternr ghostwriternr deleted the sync-docs-pr-310 branch February 9, 2026 23:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ghostwriternr ghostwriternr ghostwriternr approved these changes

@whoiskatrin whoiskatrin Awaiting requested review from whoiskatrin whoiskatrin is a code owner

@elithrar elithrar Awaiting requested review from elithrar

Assignees

@whoiskatrin whoiskatrin

@ghostwriternr ghostwriternr

Labels

product:sandbox size/m

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@Nattaworn159 @asmaylsydbdalzym808-sketch @ghostwriternr @whoiskatrin