環境変数

環境変数で、設定、シークレット、ランタイム設定をサンドボックスに渡します。

SDK の設定変数

これらの環境変数は、Sandbox SDK の動作を設定します。wrangler.jsonc の Worker vars として設定します。SDK は Worker の環境バインディングから読み取ります。

SANDBOX_TRANSPORT

型	`"http"` \| `"websocket"` \| `"rpc"`
デフォルト	`"http"`

SDK とコンテナー間の通信に使うトランスポートプロトコルを制御します。RPC トランスポートは、1 本の永続接続ですべての操作を多重化します。1 リクエストあたり多くの SDK 操作を行うときにサブリクエスト制限を避けられます。

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

[vars]
SANDBOX_TRANSPORT = "rpc"

有効なトランスポートモード、性能上の考慮、移行手順を含む完全なガイドはトランスポートモードを参照してください。

COMMAND_TIMEOUT_MS

型	`number`（ミリ秒）
デフォルト	なし（タイムアウトなし）

すべての exec() 呼び出しに対するグローバルなデフォルトタイムアウトを設定します。設定すると、この時間を超えたコマンドは呼び出し側でエラーを発生させ、接続を閉じます。

exec() のコマンド単位 timeout と、createSession() のセッション単位 commandTimeoutMs は、どちらもこの値を上書きします。タイムアウトの優先順位の詳細はコマンドの実行 - タイムアウトを参照してください。

{
	"vars": {
		"COMMAND_TIMEOUT_MS": "30000"
	}
}

[vars]
COMMAND_TIMEOUT_MS = "30000"

環境変数を設定する 3 つの方法

Sandbox SDK は、用途に応じた 3 つの環境変数設定方法を提供します。

1. setEnvVars() によるサンドボックス単位

サンドボックス内のすべてのコマンドに対して、環境変数をグローバルに設定します。

const sandbox = getSandbox(env.Sandbox, "my-sandbox");

// Set once, available for all subsequent commands
await sandbox.setEnvVars({
	DATABASE_URL: env.DATABASE_URL,
	API_KEY: env.API_KEY,
});

await sandbox.exec("python migrate.py"); // Has DATABASE_URL and API_KEY
await sandbox.exec("python seed.py"); // Has DATABASE_URL and API_KEY

// Unset variables by passing undefined
await sandbox.setEnvVars({
	API_KEY: "new-key", // Updates API_KEY
	OLD_SECRET: undefined, // Unsets OLD_SECRET
});

使う場面: 複数のコマンドで同じ環境変数が必要なとき。

変数の解除: undefined または null を渡して環境変数を解除します。

await sandbox.setEnvVars({
	API_KEY: 'new-key',     // Sets API_KEY
	OLD_SECRET: undefined,  // Unsets OLD_SECRET
	DEBUG_MODE: null        // Unsets DEBUG_MODE
});

2. exec() オプションによるコマンド単位

特定のコマンドに環境変数を渡します。

await sandbox.exec("node app.js", {
	env: {
		NODE_ENV: "production",
		PORT: "3000",
	},
});

// Also works with startProcess()
await sandbox.startProcess("python server.py", {
	env: {
		DATABASE_URL: env.DATABASE_URL,
	},
});

使う場面: コマンドごとに異なる環境変数が必要なとき、またはサンドボックス単位の変数を上書きしたいとき。

3. createSession() によるセッション単位

独自の環境変数を持つ、分離されたセッションを作成します。

const session = await sandbox.createSession({
	env: {
		DATABASE_URL: env.DATABASE_URL,
		SECRET_KEY: env.SECRET_KEY,
	},
});

// All commands in this session have these vars
await session.exec("python migrate.py");
await session.exec("python seed.py");

使う場面: 異なる環境変数を持つ分離された実行コンテキストを、同時に動かす必要があるとき。

環境変数の解除

Sandbox SDK は、undefined または null を渡して環境変数を解除できます。設定管理向けの慣用的な JavaScript パターンが使えます。

await sandbox.setEnvVars({
	// Set new values
	API_KEY: 'new-key',
	DATABASE_URL: env.DATABASE_URL,

	// Unset variables (removes them from the environment)
	OLD_API_KEY: undefined,
	TEMP_TOKEN: null
});

この変更の前: undefined を渡すとランタイムエラーになりました。

この変更の後: undefined と null はシェルで unset VARIABLE_NAME を実行します。

解除のユースケース

使用後に機密データを削除する:

// Use a temporary token
await sandbox.setEnvVars({ TEMP_TOKEN: 'abc123' });
await sandbox.exec('curl -H "Authorization: $TEMP_TOKEN" api.example.com');

// Clean up the token
await sandbox.setEnvVars({ TEMP_TOKEN: undefined });

条件付きの環境セットアップ:

await sandbox.setEnvVars({
	API_KEY: env.API_KEY,
	DEBUG_MODE: env.NODE_ENV === 'development' ? 'true' : undefined,
	PROFILING: env.ENABLE_PROFILING ? 'true' : undefined
});

システムのデフォルトに戻す:

// Unset to fall back to container's default NODE_ENV
await sandbox.setEnvVars({ NODE_ENV: undefined });

よくあるパターン

Worker のシークレットをサンドボックスに渡す

Worker のシークレットを安全にサンドボックスへ渡します。まず Wrangler でシークレットを設定します。

wrangler secret put OPENAI_API_KEY
wrangler secret put DATABASE_URL

次にサンドボックスへ渡します。

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

interface Env {
	Sandbox: DurableObjectNamespace<Sandbox>;
	OPENAI_API_KEY: string;
	DATABASE_URL: string;
}

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const sandbox = getSandbox(env.Sandbox, "user-sandbox");

		// Option 1: Set globally for all commands
		await sandbox.setEnvVars({
			OPENAI_API_KEY: env.OPENAI_API_KEY,
			DATABASE_URL: env.DATABASE_URL,
		});
		await sandbox.exec("python analyze.py");

		// Option 2: Pass per-command
		await sandbox.exec("python analyze.py", {
			env: {
				OPENAI_API_KEY: env.OPENAI_API_KEY,
			},
		});

		return Response.json({ success: true });
	},
};

デフォルトと個別の変数を組み合わせる

const defaults = { NODE_ENV: "production", LOG_LEVEL: "info" };

await sandbox.exec("npm start", {
	env: { ...defaults, PORT: "3000", API_KEY: env.API_KEY },
});

複数の分離セッション

異なる環境変数で、異なるタスクを同時に実行します。

// Production database session
const prodSession = await sandbox.createSession({
	env: { DATABASE_URL: env.PROD_DATABASE_URL },
});

// Staging database session
const stagingSession = await sandbox.createSession({
	env: { DATABASE_URL: env.STAGING_DATABASE_URL },
});

// Run migrations on both concurrently
await Promise.all([
	prodSession.exec("python migrate.py"),
	stagingSession.exec("python migrate.py"),
]);

トランスポートモードを設定する

Worker の vars に SANDBOX_TRANSPORT を設定し、HTTP、WebSocket、RPC トランスポートを切り替えます。各トランスポートの設定タイミングと方法はトランスポートモードを参照してください。

バケットマウントの認証情報

S3 互換のオブジェクトストレージをマウントするとき、SDK は内部で s3fs-fuse を使います。AWS 形式の認証情報が必要です。R2 の場合は、Cloudflare ダッシュボードで API トークンを発行し、AWS の環境変数名で渡します。

R2 API トークンを取得する:

Cloudflare ダッシュボードで R2 > Overview ↗ を開きます
Manage R2 API Tokens を選択します
Object Read & Write 権限のトークンを作成します
Access Key ID と Secret Access Key をコピーします

認証情報を Worker シークレットとして設定する:

wrangler secret put AWS_ACCESS_KEY_ID
# Paste your R2 Access Key ID

wrangler secret put AWS_SECRET_ACCESS_KEY
# Paste your R2 Secret Access Key

認証情報の自動検出でバケットをマウントする:

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

interface Env {
	Sandbox: DurableObjectNamespace<Sandbox>;
	AWS_ACCESS_KEY_ID: string;
	AWS_SECRET_ACCESS_KEY: string;
}

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const sandbox = getSandbox(env.Sandbox, "data-processor");

		// Credentials automatically detected from environment
		await sandbox.mountBucket("my-r2-bucket", "/data", {
			endpoint: "https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com",
		});

		// Access mounted bucket using standard file operations
		await sandbox.exec("python", { args: ["process.py", "/data/input.csv"] });

		return Response.json({ success: true });
	},
};

明示的な認証情報なしで mountBucket() を呼ぶと、SDK は Worker の環境から AWS_ACCESS_KEY_ID と AWS_SECRET_ACCESS_KEY を自動検出します。

認証情報を明示的に渡す（カスタムのシークレット名を使う場合）:

await sandbox.mountBucket("my-r2-bucket", "/data", {
	endpoint: "https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com",
	credentials: {
		accessKeyId: env.R2_ACCESS_KEY_ID,
		secretAccessKey: env.R2_SECRET_ACCESS_KEY,
	},
});

バケットマウントの完全なドキュメントはバケットのマウントガイドを参照してください。

環境変数の優先順位

同じ変数を複数のレベルで設定した場合、より具体的なレベルが優先されます。

コマンド単位（最優先） - exec() または startProcess() のオプションに渡した値
サンドボックスまたはセッション単位 - setEnvVars() で設定した値
コンテナーのデフォルト - Docker イメージの ENV で組み込まれた値
システムのデフォルト（最低） - オペレーティングシステムのデフォルト

例:

// In Dockerfile: ENV NODE_ENV=development

// Sandbox-level
await sandbox.setEnvVars({ NODE_ENV: "staging" });

// Command-level overrides all
await sandbox.exec("node app.js", {
	env: { NODE_ENV: "production" }, // This wins
});