ブラウザーターミナル

このガイドでは、ブラウザーベースのターミナルをサンドボックスシェルに接続する方法を示します。xterm.js と一緒に SandboxAddon を使うか、WebSocket で直接接続できます。

前提条件

サンドボックスバインディング付きの既存 Cloudflare Worker が必要です。ない場合は始めるを参照してください。

フロントエンドプロジェクトにターミナルの依存関係をインストールします。

npm install @xterm/xterm @xterm/addon-fit @cloudflare/sandbox

yarn install @xterm/xterm @xterm/addon-fit @cloudflare/sandbox

pnpm install @xterm/xterm @xterm/addon-fit @cloudflare/sandbox

bun install @xterm/xterm @xterm/addon-fit @cloudflare/sandbox

xterm.js を使わない場合、型のためだけに @cloudflare/sandbox が必要です。

Worker で WebSocket アップグレードを処理する

サンドボックスターミナルへの WebSocket 接続をプロキシするルートを追加します。次の例は、デフォルトセッションと、クエリパラメーター経由の名前付きセッションの両方に対応します。

import { getSandbox } from "@cloudflare/sandbox";

export { Sandbox } from "@cloudflare/sandbox";

export default {
	async fetch(request, env) {
		const url = new URL(request.url);

		if (
			url.pathname === "/ws/terminal" &&
			request.headers.get("Upgrade") === "websocket"
		) {
			const sandbox = getSandbox(env.Sandbox, "my-sandbox");
			const sessionId = url.searchParams.get("session");

			if (sessionId) {
				const session = await sandbox.getSession(sessionId);
				return await session.terminal(request);
			}

			return await sandbox.terminal(request, { cols: 80, rows: 24 });
		}

		return new Response("Not found", { status: 404 });
	},
};

import { getSandbox } from '@cloudflare/sandbox';

export { Sandbox } from '@cloudflare/sandbox';

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname === '/ws/terminal' && request.headers.get('Upgrade') === 'websocket') {
      const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
      const sessionId = url.searchParams.get('session');

      if (sessionId) {
        const session = await sandbox.getSession(sessionId);
        return await session.terminal(request);
      }

      return await sandbox.terminal(request, { cols: 80, rows: 24 });
    }

    return new Response('Not found', { status: 404 });
  }
};

xterm.js と SandboxAddon で接続する

ブラウザーコードでターミナルを作り、SandboxAddon を取り付けます。アドオンは WebSocket 接続、自動再接続、リサイズの転送を管理します。

import { Terminal } from "@xterm/xterm";
import { FitAddon } from "@xterm/addon-fit";
import { SandboxAddon } from "@cloudflare/sandbox/xterm";
import "@xterm/xterm/css/xterm.css";

const terminal = new Terminal({ cursorBlink: true });
const fitAddon = new FitAddon();
terminal.loadAddon(fitAddon);

const addon = new SandboxAddon({
	getWebSocketUrl: ({ sandboxId, sessionId, origin }) => {
		const params = new URLSearchParams({ id: sandboxId });
		if (sessionId) params.set("session", sessionId);
		return `${origin}/ws/terminal?${params}`;
	},
	onStateChange: (state, error) => {
		console.log(`Terminal ${state}`, error ?? "");
	},
});

terminal.loadAddon(addon);
terminal.open(document.getElementById("terminal"));
fitAddon.fit();

// Connect to the default session
addon.connect({ sandboxId: "my-sandbox" });

// Or connect to a specific session
// addon.connect({ sandboxId: 'my-sandbox', sessionId: 'development' });

window.addEventListener("resize", () => fitAddon.fit());

import { Terminal } from '@xterm/xterm';
import { FitAddon } from '@xterm/addon-fit';
import { SandboxAddon } from '@cloudflare/sandbox/xterm';
import '@xterm/xterm/css/xterm.css';

const terminal = new Terminal({ cursorBlink: true });
const fitAddon = new FitAddon();
terminal.loadAddon(fitAddon);

const addon = new SandboxAddon({
  getWebSocketUrl: ({ sandboxId, sessionId, origin }) => {
    const params = new URLSearchParams({ id: sandboxId });
    if (sessionId) params.set('session', sessionId);
    return `${origin}/ws/terminal?${params}`;
  },
  onStateChange: (state, error) => {
    console.log(`Terminal ${state}`, error ?? '');
  }
});

terminal.loadAddon(addon);
terminal.open(document.getElementById('terminal'));
fitAddon.fit();

// Connect to the default session
addon.connect({ sandboxId: 'my-sandbox' });

// Or connect to a specific session
// addon.connect({ sandboxId: 'my-sandbox', sessionId: 'development' });

window.addEventListener('resize', () => fitAddon.fit());

アドオン API の全体は、Terminal API リファレンスを参照してください。

xterm.js なしで接続する

カスタムターミナル UI を作る場合や、xterm.js のない環境で動かす場合は、WebSocket で直接接続します。プロトコルは、ターミナルデータにバイナリフレーム、制御メッセージに JSON テキストフレームを使います。

const ws = new WebSocket("wss://example.com/ws/terminal?id=my-sandbox");
ws.binaryType = "arraybuffer";

const decoder = new TextDecoder();
const encoder = new TextEncoder();

ws.addEventListener("message", (event) => {
	if (event.data instanceof ArrayBuffer) {
		// Terminal output (binary) — includes ANSI escape sequences
		const text = decoder.decode(event.data);
		appendToDisplay(text);
		return;
	}

	// Control message (JSON text)
	const msg = JSON.parse(event.data);

	switch (msg.type) {
		case "ready":
			// Terminal is accepting input — send initial resize
			ws.send(JSON.stringify({ type: "resize", cols: 80, rows: 24 }));
			break;

		case "exit":
			console.log(`Shell exited: code ${msg.code}`);
			break;

		case "error":
			console.error("Terminal error:", msg.message);
			break;
	}
});

// Send keystrokes as binary
function sendInput(text) {
	if (ws.readyState === WebSocket.OPEN) {
		ws.send(encoder.encode(text));
	}
}

const ws = new WebSocket('wss://example.com/ws/terminal?id=my-sandbox');
ws.binaryType = 'arraybuffer';

const decoder = new TextDecoder();
const encoder = new TextEncoder();

ws.addEventListener('message', (event) => {
  if (event.data instanceof ArrayBuffer) {
    // Terminal output (binary) — includes ANSI escape sequences
    const text = decoder.decode(event.data);
    appendToDisplay(text);
    return;
  }

  // Control message (JSON text)
  const msg = JSON.parse(event.data);

  switch (msg.type) {
    case 'ready':
      // Terminal is accepting input — send initial resize
      ws.send(JSON.stringify({ type: 'resize', cols: 80, rows: 24 }));
      break;

    case 'exit':
      console.log(`Shell exited: code ${msg.code}`);
      break;

    case 'error':
      console.error('Terminal error:', msg.message);
      break;
  }
});

// Send keystrokes as binary
function sendInput(text: string): void {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(encoder.encode(text));
  }
}

プロトコルの要点:

接続前に binaryType を arraybuffer に設定します。
前回の接続からバッファされた出力は、ready メッセージより前にバイナリフレームとして届きます。
キー入力はバイナリ（UTF-8）で送ります。制御メッセージ（resize）は JSON テキストで送ります。
クライアントが切断しても PTY は生きたままです。再接続すると、バッファされた出力が再生されます。

プロトコル仕様の全体は、API リファレンスの WebSocket プロトコルを参照してください。

ベストプラクティス

常に FitAddon を使う — ないと、ターミナルの寸法がコンテナと合わず、テキストの折り返しがずれます。
リサイズイベントを処理する — ウィンドウのリサイズ時に fitAddon.fit() を呼び、ターミナルと PTY を同期させます。
アンマウント時に後始末する — ページからターミナルを外すときは addon.disconnect() を呼び出します。
ターミナルをユーザサンドボックスにスコープする — 同じワークスペース内の複数ターミナルコンテキストにはセッションを使います。ユーザーごとに別サンドボックスを使います。