Add PTY terminal passthrough for browser clients

.changeset/pty-support.md

@@ -0,0 +1,29 @@
+---
+'@cloudflare/sandbox': patch
+---
+
+Add terminal support for browser-based terminal UIs.
+
+Build interactive terminal experiences by connecting xterm.js to container PTYs via WebSocket. Terminals reconnect automatically with output history preserved, and each session gets its own isolated terminal.
+
+```typescript
+// Proxy WebSocket to container terminal
+return sandbox.terminal(request, { cols: 80, rows: 24 });
+
+// Multiple isolated terminals in the same sandbox
+const session = await sandbox.getSession('dev');
+return session.terminal(request);
+```
+
+Also exports `@cloudflare/sandbox/xterm` with a `SandboxAddon` for xterm.js — handles WebSocket connection, reconnection with exponential backoff, and terminal resize forwarding.
+
+```typescript
+import { SandboxAddon } from '@cloudflare/sandbox/xterm';
+
+const addon = new SandboxAddon({
+  getWebSocketUrl: ({ sandboxId, origin }) =>
+    `${origin}/ws/terminal?id=${sandboxId}`
+});
+terminal.loadAddon(addon);
+addon.connect({ sandboxId: 'my-sandbox' });
+```

.github/workflows/pullrequest.yml

@@ -257,11 +257,16 @@ jobs:
         run: |
           echo "worker_url=https://${{ steps.env-name.outputs.worker_name }}.${{ env.CF_ACCOUNT_SUBDOMAIN }}.workers.dev" >> $GITHUB_OUTPUT
 
-      # Run E2E tests against deployed worker
+      - name: Install Playwright browsers
+        run: npx playwright install chromium
+
       - name: Run E2E tests
-        run: npx vitest run --config vitest.e2e.config.ts
+        run: |
+          npx vitest run --config vitest.e2e.config.ts
+          npx playwright test --config tests/e2e/browser/playwright.config.ts
         env:
           TEST_WORKER_URL: ${{ steps.get-url.outputs.worker_url }}
+          TEST_SANDBOX_ID: browser-test-${{ github.run_id }}-${{ matrix.transport }}
           CI: true
           CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
           AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}

.github/workflows/release.yml

@@ -208,10 +208,16 @@ jobs:
           workingDirectory: tests/e2e/test-worker
           command: deploy --name ${{ env.E2E_WORKER_NAME }}
 
+      - name: Install Playwright browsers
+        run: npx playwright install chromium
+
       - name: Run E2E tests
         env:
           TEST_WORKER_URL: https://${{ env.E2E_WORKER_NAME }}.${{ env.CF_ACCOUNT_SUBDOMAIN }}.workers.dev
-        run: npm run test:e2e
+          TEST_SANDBOX_ID: browser-test-release-${{ github.run_id }}
+        run: |
+          npx vitest run --config vitest.e2e.config.ts
+          npx playwright test --config tests/e2e/browser/playwright.config.ts
 
       - name: Cleanup test deployment
         if: always()

.opencode/skill/testing/SKILL.md

@@ -50,11 +50,14 @@ npm test -w @repo/sandbox-container   # Container tests only
 **Commands**:
 
 ```bash
-npm run test:e2e                                                    # All E2E tests
-npm run test:e2e -- -- tests/e2e/process-lifecycle-workflow.test.ts # Single file
-npm run test:e2e -- -- tests/e2e/git-clone-workflow.test.ts -t 'test name'  # Single test
+npm run test:e2e                                                           # All E2E tests (vitest + browser)
+npm run test:e2e:vitest -- -- tests/e2e/process-lifecycle-workflow.test.ts # Single vitest file
+npm run test:e2e:vitest -- -- tests/e2e/git-clone-workflow.test.ts -t 'test name'  # Single vitest test
+npm run test:e2e:browser                                                   # Browser tests only (Playwright)
 ```
 
+**Note**: Use `test:e2e:vitest` when filtering tests. The `test:e2e` wrapper doesn't support argument passthrough.
+
 **Key patterns**:
 
 - All tests share ONE container for performance

AGENTS.md

@@ -67,15 +67,18 @@ npm run build:clean        # Force rebuild without cache
 See the **testing** skill for detailed guidance on unit vs E2E tests.
 
 ```bash
-npm test                                    # All unit tests
-npm test -w @cloudflare/sandbox             # SDK unit tests only
-npm test -w @repo/sandbox-container         # Container unit tests only
-
-npm run test:e2e                            # All E2E tests (requires Docker)
-npm run test:e2e -- -- tests/e2e/file.ts    # Single E2E file
-npm run test:e2e -- -- tests/e2e/file.ts -t 'test name'  # Single test
+npm test                                           # All unit tests
+npm test -w @cloudflare/sandbox                    # SDK unit tests only
+npm test -w @repo/sandbox-container                # Container unit tests only
+
+npm run test:e2e                                   # All E2E tests (vitest + browser, requires Docker)
+npm run test:e2e:vitest -- -- tests/e2e/file.ts   # Single vitest E2E file
+npm run test:e2e:vitest -- -- tests/e2e/file.ts -t 'test name'  # Single vitest E2E test
+npm run test:e2e:browser                           # Browser E2E tests only (Playwright)
 ```
 
+**Note**: Use `test:e2e:vitest` when filtering tests. The `test:e2e` wrapper doesn't support argument passthrough.
+
 ### Code Quality
 
 ```bash

CONTRIBUTING.md

@@ -171,13 +171,18 @@ Located in `tests/e2e/`:
 Run with: `npm run test:e2e`
 
 ```bash
-# Run a single E2E test file
-npm run test:e2e -- -- tests/e2e/process-lifecycle-workflow.test.ts
+# Run a single vitest E2E test file
+npm run test:e2e:vitest -- -- tests/e2e/process-lifecycle-workflow.test.ts
 
-# Run a specific test within a file
-npm run test:e2e -- -- tests/e2e/git-clone-workflow.test.ts -t 'should handle cloning to default directory'
+# Run a specific vitest E2E test within a file
+npm run test:e2e:vitest -- -- tests/e2e/git-clone-workflow.test.ts -t 'should handle cloning to default directory'
+
+# Run browser E2E tests only (Playwright)
+npm run test:e2e:browser
 ```
 
+**Note**: Use `test:e2e:vitest` when filtering tests. The `test:e2e` wrapper runs both vitest and browser tests sequentially but doesn't support argument passthrough.
+
 **See `docs/E2E_TESTING.md` for the complete guide on writing E2E tests.**
 
 ### Writing Tests

docs/E2E_TESTING.md

@@ -140,16 +140,21 @@ test('should start server', async () => {
 ## Running Tests
 
 ```bash
-# All E2E tests
+# All E2E tests (runs vitest E2E tests, then browser E2E tests sequentially)
 npm run test:e2e
 
-# Single file
-npm run test:e2e -- -- tests/e2e/process-lifecycle-workflow.test.ts
+# Single vitest E2E file
+npm run test:e2e:vitest -- -- tests/e2e/process-lifecycle-workflow.test.ts
 
-# Single test by name
-npm run test:e2e -- -- tests/e2e/git-clone-workflow.test.ts -t 'should clone repo'
+# Single vitest E2E test by name
+npm run test:e2e:vitest -- -- tests/e2e/git-clone-workflow.test.ts -t 'should clone repo'
+
+# Browser E2E tests only (Playwright)
+npm run test:e2e:browser
 ```
 
+**Note on argument passthrough**: Use `test:e2e:vitest` (not `test:e2e`) when passing arguments to filter tests. The `test:e2e` script runs both vitest and browser tests sequentially but doesn't support argument passthrough due to turborepo limitations.
+
 ## Debugging
 
 - Tests auto-retry once on failure (`retry: 1` in config)

examples/collaborative-terminal/.gitignore

@@ -0,0 +1,18 @@
+.DS_Store
+.env
+/node_modules/
+*.tsbuildinfo
+
+# React Router
+/.react-router/
+/build/
+
+# Cloudflare
+.mf
+.wrangler
+.dev.vars*
+worker-configuration.d.ts
+
+
+!.dev.vars.example
+!.env.example

examples/collaborative-terminal/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "files.associations": {
+    "wrangler.json": "jsonc"
+  }
+}

examples/collaborative-terminal/Dockerfile

@@ -0,0 +1,4 @@
+FROM docker.io/cloudflare/sandbox:0.7.0
+
+# Required during local development to access exposed ports
+EXPOSE 8080

examples/collaborative-terminal/README.md

@@ -0,0 +1,111 @@
+# Collaborative Terminal
+
+Real-time terminal sharing powered by Cloudflare Sandbox. Like Google Docs, but for your shell.
+
+Multiple users join a room, share a single sandbox terminal, and see each other's input in real-time with presence indicators and typing notifications.
+
+## Features
+
+- **Shared terminal**: Every participant sees the same PTY output as it happens
+- **Room system**: Create rooms, share links, browse and join active rooms
+- **Presence**: See who's in the room with colored avatars and typing indicators
+- **Session isolation**: Each room gets its own sandbox session so rooms don't interfere
+- **Live room list**: Homepage updates in real-time as rooms are created or emptied
+
+## Architecture
+
+The example uses three Durable Objects working together:
+
+```
+Browser (xterm.js + SandboxAddon)
+    |
+    |-- /ws/room/:id ----> Room DO         Presence, user list, typing
+    |
+    \-- /ws/terminal/:sessionId
+            |
+            v
+        Sandbox DO <---> Container PTY    Direct WebSocket passthrough
+            |
+RoomRegistry DO                           Tracks active rooms globally
+```
+
+**Terminal connection**: The browser connects directly to the sandbox container's PTY through a WebSocket that the SDK proxies transparently. There's no JSON protocol for terminal I/O — raw bytes flow between xterm.js and the container's PTY via `SandboxAddon`.
+
+**Room connection**: A separate WebSocket to the Room DO handles presence (joins, leaves, typing indicators). This keeps the collaboration layer decoupled from terminal I/O.
+
+## How It Works
+
+### Server side
+
+The Worker routes requests to the appropriate Durable Object:
+
+```typescript
+// Terminal: proxy WebSocket directly to a sandbox session's PTY
+const sandbox = getSandbox(env.Sandbox, 'shared-terminal');
+const session = await sandbox.getSession(sessionId);
+return session.terminal(request);
+```
+
+Each room maps to a session ID (`room-${roomId}`), so different rooms get isolated shell environments within the same sandbox container.
+
+### Client side
+
+The terminal component uses `SandboxAddon` from `@cloudflare/sandbox/xterm` to handle the WebSocket connection, resize events, and reconnection:
+
+```typescript
+import { SandboxAddon } from '@cloudflare/sandbox/xterm';
+
+const sandboxAddon = new SandboxAddon({
+  getWebSocketUrl: ({ origin, sessionId }) =>
+    `${origin}/ws/terminal/${sessionId}`,
+  onStateChange: (state) => setState(state)
+});
+
+terminal.loadAddon(sandboxAddon);
+sandboxAddon.connect({ sandboxId: 'shared-terminal', sessionId });
+```
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 20+
+- Docker (for local development)
+- Cloudflare account with container access
+
+### Install and run
+
+```bash
+npm install
+npm run dev
+```
+
+Open http://localhost:5173, create a room, and share the link.
+
+### Deploy
+
+```bash
+npm run deploy
+```
+
+After first deployment, wait 2-3 minutes for container provisioning before making requests.
+
+## Project Structure
+
+```
+workers/
+  app.ts            Main Worker — routes requests, creates rooms
+  room.ts           Room DO — manages connected users and presence
+  registry.ts       RoomRegistry DO — tracks active rooms globally
+  types/protocol.ts WebSocket message types for the room protocol
+
+app/
+  routes/home.tsx       Homepage with room creation and active room list
+  routes/room.tsx       Room page with terminal, sidebar, and presence
+  components/
+    Terminal.client.tsx xterm.js setup with SandboxAddon
+    UserAvatars.tsx     Colored avatar circles with typing indicators
+  hooks/
+    usePresence.ts      WebSocket hook for room presence state
+    useActiveRooms.ts   WebSocket hook for live room list from registry
+```

examples/collaborative-terminal/app/app.css

@@ -0,0 +1,14 @@
+@import "tailwindcss";
+
+@theme {
+  --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif,
+    "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
+  --font-mono: "JetBrains Mono", "Fira Code", "SF Mono", Menlo, Monaco,
+    "Courier New", monospace;
+}
+
+html,
+body {
+  @apply bg-zinc-950 text-zinc-100;
+  color-scheme: dark;
+}