add PTY support

.changeset/pty-support.md

@@ -0,0 +1,30 @@
+---
+'@cloudflare/sandbox': minor
+---
+
+Add PTY (pseudo-terminal) support for interactive terminal sessions.
+
+New `sandbox.pty` namespace with:
+
+- `create()` - Create a new PTY session
+- `attach(sessionId)` - Attach PTY to existing session
+- `getById(id)` - Reconnect to existing PTY
+- `list()` - List all PTY sessions
+
+PTY handles support:
+
+- `write(data)` - Send input
+- `resize(cols, rows)` - Resize terminal
+- `kill()` - Terminate PTY
+- `onData(cb)` - Receive output
+- `onExit(cb)` - Handle exit
+- `exited` - Promise for exit code
+- Async iteration for scripting
+
+Example:
+
+```typescript
+const pty = await sandbox.pty.create({ cols: 80, rows: 24 });
+pty.onData((data) => terminal.write(data));
+pty.write('ls -la\n');
+```

.github/workflows/claude-code-review.yml

@@ -148,7 +148,6 @@ jobs:
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           plugin_marketplaces: |
-            https://github.com/anthropics/claude-plugins-official.git
             https://github.com/obra/superpowers-marketplace.git
           plugins: |
             pr-review-toolkit@claude-plugins-official

examples/collaborative-terminal/Dockerfile

@@ -0,0 +1,17 @@
+# Collaborative Terminal Dockerfile
+#
+# IMPORTANT: PTY support requires sandbox image version 0.7.0 or later.
+#
+# For local development with PTY support, first build the base image:
+#   cd ../..  # Go to monorepo root  
+#   docker build --platform linux/amd64 -f packages/sandbox/Dockerfile --target default -t sandbox-pty-local .
+#
+# The wrangler dev server will then use this Dockerfile which extends sandbox-pty-local.
+#
+FROM docker.io/cloudflare/sandbox:0.0.0-pr-310-ad66e85
+
+# Create home directory for terminal sessions
+RUN mkdir -p /home/user && chmod 777 /home/user
+
+# Expose container port
+EXPOSE 3000

examples/collaborative-terminal/README.md

@@ -0,0 +1,165 @@
+# Collaborative Terminal
+
+**Google Docs for Bash** - A multi-user terminal where multiple people can see the same PTY output in real-time and take turns sending commands.
+
+This example demonstrates:
+
+- **PTY Support**: Using the Sandbox SDK's PTY API for interactive terminal sessions
+- **WebSocket Streaming**: Real-time output broadcast to all connected users
+- **Collaborative Workflows**: Multiple users sharing a single terminal session
+- **Presence Indicators**: See who's connected and who's typing
+
+## Features
+
+- Create terminal rooms that others can join via shareable link
+- Real-time terminal output synchronized across all participants
+- User presence list with colored indicators
+- "Typing" indicators showing who's sending commands
+- Terminal history buffering so new users see previous output
+- Automatic cleanup when all users disconnect
+
+## Architecture
+
+```
+┌──────────────┐     WebSocket     ┌─────────────────┐     PTY API    ┌───────────┐
+│   Browser    │◄──────────────────►  Cloudflare     │◄──────────────►│  Sandbox  │
+│   (xterm)    │                   │     Worker      │                │ Container │
+└──────────────┘                   └─────────────────┘                └───────────┘
+       │                                   │
+       │                                   │
+       ▼                                   ▼
+  User Input                         Broadcast PTY
+  ─────────►                         output to all
+                                     connected users
+```
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 20+
+- Docker (for local development)
+- Cloudflare account with container access (beta)
+
+### Important: PTY Support Required
+
+This example requires PTY (pseudo-terminal) support which is available in sandbox image version **0.7.0 or later**. If using an older image, you'll need to build a local image with PTY support:
+
+```bash
+# From the monorepo root
+cd ../..
+docker build -f packages/sandbox/Dockerfile --target default -t sandbox-local .
+
+# Then update examples/collaborative-terminal/Dockerfile to use:
+# FROM sandbox-local
+```
+
+### Installation
+
+```bash
+cd examples/collaborative-terminal
+npm install
+```
+
+### Development
+
+```bash
+npm run dev
+```
+
+This starts a local development server. Open http://localhost:5173 to access the app.
+
+### Deploy
+
+```bash
+npm run deploy
+```
+
+## Usage
+
+1. **Create a Room**: Click "Create New Room" to start a new terminal session
+2. **Share the Link**: Click "Copy Link" to share the room with others
+3. **Join a Room**: Enter a room ID to join an existing session
+4. **Start Terminal**: Click "Start Terminal Session" to launch bash
+5. **Collaborate**: All connected users see the same terminal output and can send commands
+
+## How It Works
+
+### Backend (Worker)
+
+The Cloudflare Worker manages:
+
+1. **Room State**: Tracks connected users and active PTY sessions per room
+2. **WebSocket Connections**: Handles real-time communication with clients
+3. **PTY Lifecycle**: Creates/destroys PTY sessions via the Sandbox SDK
+4. **Output Broadcasting**: Forwards PTY output to all connected WebSocket clients
+
+```typescript
+// Create PTY and subscribe to output
+const pty = await sandbox.pty.create({
+  cols: 80,
+  rows: 24,
+  command: ['/bin/bash']
+});
+
+pty.onData((data) => {
+  // Broadcast to all connected users
+  broadcast(roomId, { type: 'pty_output', data });
+});
+```
+
+### Frontend (React + xterm.js)
+
+The React app provides:
+
+1. **Terminal Rendering**: Uses xterm.js for terminal emulation
+2. **WebSocket Client**: Connects to the worker for real-time updates
+3. **User Management**: Displays connected users with presence indicators
+4. **Input Handling**: Forwards keystrokes to the shared PTY
+
+```typescript
+// Handle terminal input
+term.onData((data) => {
+  ws.send(JSON.stringify({ type: 'pty_input', data }));
+});
+
+// Handle PTY output from server
+ws.onmessage = (event) => {
+  const msg = JSON.parse(event.data);
+  if (msg.type === 'pty_output') {
+    term.write(msg.data);
+  }
+};
+```
+
+## API Reference
+
+### WebSocket Messages
+
+**Client → Server:**
+
+| Type         | Description        | Fields         |
+| ------------ | ------------------ | -------------- |
+| `start_pty`  | Create PTY session | `cols`, `rows` |
+| `pty_input`  | Send input to PTY  | `data`         |
+| `pty_resize` | Resize terminal    | `cols`, `rows` |
+
+**Server → Client:**
+
+| Type          | Description         | Fields                       |
+| ------------- | ------------------- | ---------------------------- |
+| `connected`   | Initial connection  | `userId`, `users`, `history` |
+| `user_joined` | User joined room    | `user`, `users`              |
+| `user_left`   | User left room      | `userId`, `users`            |
+| `pty_started` | PTY session created | `ptyId`                      |
+| `pty_output`  | Terminal output     | `data`                       |
+| `pty_exit`    | PTY session ended   | `exitCode`                   |
+| `user_typing` | User sent input     | `user`                       |
+
+## Customization Ideas
+
+- **Access Control**: Add authentication to restrict who can join/type
+- **Command History**: Store and replay command history
+- **Multiple Terminals**: Support multiple PTY sessions per room
+- **Recording**: Record sessions for playback
+- **Chat**: Add a sidebar chat for discussion

examples/collaborative-terminal/index.html

@@ -0,0 +1,36 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#09090b" />
+    <meta name="description" content="Real-time collaborative terminal sharing. Like Google Docs, but for your shell. Powered by Cloudflare Sandboxes." />
+    <meta property="og:title" content="Collaborative Terminal" />
+    <meta property="og:description" content="Real-time terminal sharing. Code together, debug together, ship together." />
+    <meta property="og:type" content="website" />
+    <title>Collaborative Terminal | Cloudflare Sandbox</title>
+    <link rel="icon" type="image/x-icon" href="/favicon.ico" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
+    <style>
+      * {
+        box-sizing: border-box;
+      }
+      html, body {
+        margin: 0;
+        padding: 0;
+        background: #09090b;
+        -webkit-font-smoothing: antialiased;
+        -moz-osx-font-smoothing: grayscale;
+      }
+      #root {
+        min-height: 100vh;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

examples/collaborative-terminal/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@cloudflare/sandbox-collaborative-terminal-example",
+  "version": "1.0.0",
+  "description": "Collaborative terminal - Google Docs for bash using PTY support",
+  "private": true,
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "deploy": "vite build && wrangler deploy",
+    "types": "wrangler types env.d.ts --include-runtime false",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "sandbox",
+    "pty",
+    "terminal",
+    "collaborative"
+  ],
+  "author": "",
+  "license": "ISC",
+  "type": "module",
+  "dependencies": {
+    "@xterm/addon-fit": "^0.10.0",
+    "@xterm/addon-web-links": "^0.12.0",
+    "@xterm/addon-webgl": "^0.19.0",
+    "@xterm/xterm": "^5.5.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@cloudflare/sandbox": "*",
+    "@cloudflare/vite-plugin": "^1.15.2",
+    "@cloudflare/workers-types": "^4.20251126.0",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "typescript": "^5.9.3",
+    "vite": "^7.2.4",
+    "wrangler": "^4.50.0"
+  }
+}