2026 年の非推奨機能からの移行ガイド

このガイドでは、非推奨の告知で非推奨になった Sandbox SDK 機能からの移行を説明します。これらの API の上に新しい作業を作らないでください。安定版パッケージでこの整理を終えてから、準備ができたら 1.0 プレビューへ進みます。

告知と理由は、非推奨の changelog エントリを参照してください。

移行の前に

トランスポートまたはセッション設定を変える前に、最新の Sandbox SDK リリースへ更新します。プロジェクトが 0.9.1 より前のバージョンなら、RPC トランスポートへ切り替える前に、新しい @cloudflare/sandbox パッケージとコンテナーイメージをデプロイします。enableDefaultSession: false によるセッション分離には、Sandbox SDK 0.10.3 以降が必要です。0.9.1〜0.10.2 では、先にアップグレードしてからフラグを設定します。

コードベースで、非推奨の設定と API を検索します。

rg 'SANDBOX_TRANSPORT|transport:|exposePort\(|enableDefaultSession|execStream\(|readFileStream|writeFileStream'

ストリーム専用のファイルヘルパーを使うコードや、別々の exec() 呼び出しをまたいでシェル状態が引き継がれる前提のコードも確認します。

HTTP と WebSocket のトランスポート

HTTP と WebSocket のトランスポートは非推奨です。RPC トランスポートへ切り替えます。

Worker 内のすべてのサンドボックスに RPC トランスポートを設定するには、Worker の設定で SANDBOX_TRANSPORT を設定します。

{
	"vars": {
		"SANDBOX_TRANSPORT": "rpc"
	}
}

[vars]
SANDBOX_TRANSPORT = "rpc"

特定のサンドボックスに RPC トランスポートを設定するには、getSandbox() に transport: "rpc" を渡します。

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

const sandbox = getSandbox(env.Sandbox, "user-123", {
	transport: "rpc",
});

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

const sandbox = getSandbox(env.Sandbox, "user-123", {
	transport: "rpc",
});

詳細はトランスポートモードを参照してください。

デスクトップ

デスクトップ機能は 0.10.2 で削除されました。この機能は、computer-use 形式の自動化向けに、サンドボックス内でフル Linux デスクトップを動かしていました。同じ形がまだ必要な場合は、組み込みのデスクトップ API ではなく拡張で作り直します。サンドボックス内デスクトップが不要な、分離されたコマンド実行、ファイル操作、ランタイムワークフローには、Sandbox SDK を使い続けます。

ポートの公開

公開 URL には、exposePort() の代わりに tunnels API を使います。tunnels API には RPC トランスポートが必要です。

開発、デモ、短命の URL にはクイックトンネルを使います。本番トラフィック、Webhook 受信、OAuth コールバック、自分が管理するゾーン上の安定したホスト名には、ネームドトンネルを使います。

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

const sandbox = getSandbox(env.Sandbox, "my-sandbox", {
	transport: "rpc",
});

const server = await sandbox.startProcess("python -m http.server 8080");
await server.waitForPort(8080);

const tunnel = await sandbox.tunnels.get(8080);
return Response.json({ url: tunnel.url });

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

const sandbox = getSandbox(env.Sandbox, "my-sandbox", {
	transport: "rpc",
});

const server = await sandbox.startProcess("python -m http.server 8080");
await server.waitForPort(8080);

const tunnel = await sandbox.tunnels.get(8080);
return Response.json({ url: tunnel.url });

exposePort() の流れで proxyToSandbox() を使い、認証の注入やレスポンスの書き換えをしていた場合は、公開 URL をトンネルへ移す前に、その動作を考慮します。

詳細はトンネルとサービスの公開を参照してください。

デフォルトセッション

getSandbox() で enableDefaultSession: false を設定します。明示的なセッションなしの操作は、その後は分離して動き、以前の呼び出しのシェル状態を引き継ぎません。

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

const sandbox = getSandbox(env.Sandbox, "user-123", {
	enableDefaultSession: false,
	transport: "rpc",
});

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

const sandbox = getSandbox(env.Sandbox, "user-123", {
	enableDefaultSession: false,
	transport: "rpc",
});

cd /workspace/app のようなコマンドが後続の exec() に効くことを想定している場合は、明示的なセッションを作り、関連するコマンドをそのセッションで実行します。

const buildSession = await sandbox.createSession({
	id: "build",
	cwd: "/workspace/app",
});

await buildSession.exec("npm install");
await buildSession.exec("npm test");

const buildSession = await sandbox.createSession({
	id: "build",
	cwd: "/workspace/app",
});

await buildSession.exec("npm install");
await buildSession.exec("npm test");

単発のコマンドでは、永続化したシェル状態に頼らず、cwd または env を exec() へ直接渡します。

await sandbox.exec("npm test", {
	cwd: "/workspace/app",
	env: {
		NODE_ENV: "test",
	},
});

await sandbox.exec("npm test", {
	cwd: "/workspace/app",
	env: {
		NODE_ENV: "test",
	},
});

詳細はサンドボックスオプションとセッションを参照してください。

ストリーミング API

Sandbox SDK は、個別のストリーミング API を、ベースの exec()、readFile()、writeFile() メソッドへ集約しています。ストリーム専用ヘルパーに依存するコードを確認し、ストリーミング動作をサポートする箇所ではベース API へ移します。

コマンド出力では、ストリーミングコールバック付きの exec() を使います。

await sandbox.exec("npm install", {
	stream: true,
	onOutput: (stream, data) => {
		console.log(`[${stream}] ${data}`);
	},
});

await sandbox.exec("npm install", {
	stream: true,
	onOutput: (stream, data) => {
		console.log(`[${stream}] ${data}`);
	},
});

大きなファイルやバイナリファイルでは、RPC トランスポート付きのベースファイル API を使います。writeFile() に ReadableStream を渡すか、encoding: "none" でファイルをストリームとして読みます。

const request = await fetch("https://example.com/archive.tar.gz");

if (!request.body) {
	throw new Error("Expected archive response body");
}

await sandbox.writeFile("/workspace/archive.tar.gz", request.body);

const file = await sandbox.readFile("/workspace/archive.tar.gz", {
	encoding: "none",
});

return new Response(file.content, {
	headers: { "Content-Type": file.mimeType },
});

const request = await fetch("https://example.com/archive.tar.gz");

if (!request.body) {
	throw new Error("Expected archive response body");
}

await sandbox.writeFile("/workspace/archive.tar.gz", request.body);

const file = await sandbox.readFile("/workspace/archive.tar.gz", {
	encoding: "none",
});

return new Response(file.content, {
	headers: { "Content-Type": file.mimeType },
});

詳細はコマンドとファイルを参照してください。

移行の確認

非推奨 API を削除した Sandbox SDK リリースに依存する前に、このチェックリストを使います。

RPC トランスポートを SANDBOX_TRANSPORT=rpc または transport: "rpc" で設定している。
websocket または http のトランスポート設定が残っていない。
移行した経路に exposePort() の利用が残っていない。
enableDefaultSession が false になっている。
状態を持つコマンドワークフローは sandbox.createSession() を使っている。
単発コマンドは cwd と env を直接渡している。
ファイルとコマンドのストリーミングコードはベース API を使っている。
Worker をデプロイし、スモークテスト済みである。

コーディングエージェント

Cloudflare Skills ↗ を入れたコーディングエージェント（Agent setup）は、現行の安定版パッケージでの作業に sandbox-stable を使い、安定版に留まったまま非推奨 API を整理するときは このガイド に従います。Sandbox SDK 1.0（@next）へ完全に移る場合は、代わりに sandbox-migrate-to-next（および 1.0 移行ガイド）を使います。

1.0 プレビュー

このガイドの安定版向け変更を終えたら、準備ができ次第、@cloudflare/sandbox@next の Sandbox SDK 1.0 プレビューへ進みます。そのプレビューが、次の安定版メジャーリリースへの道です。

Sandbox SDK 1.0 プレビューと 1.0 プレビューへの移行を参照してください。