Terminal connections

Last updated Sep 30, 2026 Note

This page documents Sandbox SDK 0.x for existing applications. For new applications, refer to Open a terminal in the browser. To move an existing application to @cloudflare/sandbox 1.0, refer to Migrate from Sandbox SDK 0.x.

Terminal connections let browser-based UIs interact directly with sandbox shells. Instead of executing discrete commands with exec(), a terminal connection opens a persistent, bidirectional channel to a bash shell — the same model as SSH or a local terminal emulator.

How terminal connections work

Terminal connections use WebSockets to stream raw bytes between a browser terminal (like xterm.js ↗︎) and a pseudo-terminal (PTY) process running inside the sandbox container.

Browser (xterm.js) <-- WebSocket --> Worker <-- proxy --> Container PTY (bash)
  1. The browser sends a WebSocket upgrade request to your Worker
  2. Your Worker calls sandbox.terminal(request), which proxies the upgrade to the container
  3. The container spawns a bash shell attached to a PTY
  4. Raw bytes flow bidirectionally — keystrokes in, terminal output out

This is fundamentally different from exec():

  • exec() runs a single command to completion and returns the result
  • terminal() opens a persistent shell where users type commands interactively

Output buffering

The container buffers terminal output in a ring buffer. When a client disconnects and reconnects, the server replays buffered output so the terminal appears unchanged. This means:

  • Short network interruptions are invisible to users
  • Reconnected terminals show previous output without re-running commands
  • The buffer has a fixed size, so very old output may be lost

No client-side code is needed to handle buffering — the container manages it transparently.

Automatic reconnection

Network interruptions are common in browser-based applications. Terminal connections handle this through a combination of server-side buffering (described above) and client-side reconnection with exponential backoff.

The SandboxAddon for xterm.js implements this automatically. If you are building a custom client, you are responsible for your own reconnection logic — the server-side buffering works regardless of which client connects. Refer to the WebSocket protocol reference for details on the connection lifecycle.

Session-specific terminals

Each session can have its own terminal with independent shell state:

const devSession = await sandbox.createSession({
    id: "dev",
    cwd: "/workspace/frontend",
    env: { NODE_ENV: "development" },
});

const testSession = await sandbox.createSession({
    id: "test",
    cwd: "/workspace",
    env: { NODE_ENV: "test" },
});

// Each session's terminal has its own working directory,
// environment variables, and command history

Multiple browser clients can connect to the same session's terminal simultaneously. They all see the same shell output and can send input. Use this pattern for intentional collaboration inside one workspace, not to separate independent users.

WebSocket protocol

Terminal connections use binary WebSocket frames for terminal I/O (for performance) and JSON text frames for control and status messages (for structure). This keeps the data path fast while still allowing structured communication for operations like terminal resizing.

For the full protocol specification, including the connection lifecycle and message formats, refer to the Terminal API reference.

When to use terminals vs commands

Use case Approach
Run a command and get the result exec() or execStream()
Interactive shell for end users terminal()
Long-running process with real-time output startProcess() + streamProcessLogs()
Collaborative terminal sharing terminal() with shared session

Was this helpful?

YesNo

On this page

Terminal connections - 图1Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/sandbox/sdk/concepts/terminal/#page","headline":"Terminal connections","description":"Sandbox SDK 0.x terminal connections stream bidirectional data between browser UIs and container shells.","url":"https://developers.cloudflare.com/sandbox/sdk/concepts/terminal/","inLanguage":"en","image":"https://developers.cloudflare.com/sandbox/sdk/concepts/terminal/og.png?v=4947ea78da02787b","dateModified":"2026-09-30","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Configure Sandbox SDK 0.x deployments with Wrangler, Dockerfiles, environment variables, and transport modes. title: Configuration image: https://developers.cloudflare.com/sandbox/sdk/configuration/og.png?v=e954ba36141524b7

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/sandbox/llms.txt
Use this file to discover all available pages before exploring further.