Wrangler の設定

最小構成

Sandbox SDK を使うための最小構成です。

{
	"name": "my-sandbox-worker",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"compatibility_flags": ["nodejs_compat"],
	"containers": [
		{
			"class_name": "Sandbox",
			"image": "./Dockerfile",
		},
	],
	"durable_objects": {
		"bindings": [
			{
				"class_name": "Sandbox",
				"name": "Sandbox",
			},
		],
	},
	"migrations": [
		{
			"new_sqlite_classes": ["Sandbox"],
			"tag": "v1",
		},
	],
}

name = "my-sandbox-worker"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-09-20"
compatibility_flags = [ "nodejs_compat" ]

[[containers]]
class_name = "Sandbox"
image = "./Dockerfile"

[[durable_objects.bindings]]
class_name = "Sandbox"
name = "Sandbox"

[[migrations]]
new_sqlite_classes = [ "Sandbox" ]
tag = "v1"

必須設定

Sandbox SDK は Cloudflare Containers の上に構築されています。設定には次の 3 つのセクションが必要です。

containers - コンテナイメージ（ランタイム環境）を定義します
durable_objects.bindings - Sandbox Durable Object を Worker にバインドします
migrations - Durable Object クラスを初期化します

上の最小構成に、必須設定はすべて含まれています。詳細な設定オプションは Containers の設定ドキュメントを参照してください。

バックアップストレージ

バックアップと復元 API を使うには、R2 バケットバインディングと署名付き URL の資格情報が必要です。コンテナは署名付き URL を使って、バックアップアーカイブを R2 に直接アップロード / ダウンロードします。そのため R2 API トークンの資格情報が必要です。

1. R2 バケットを作成する

npx wrangler r2 bucket create my-backup-bucket

2. バインディングと環境変数を追加する

{
	"vars": {
		"BACKUP_BUCKET_NAME": "my-backup-bucket",
		"CLOUDFLARE_ACCOUNT_ID": "<YOUR_ACCOUNT_ID>",
	},
	"r2_buckets": [
		{
			"binding": "BACKUP_BUCKET",
			"bucket_name": "my-backup-bucket",
		},
	],
}

[vars]
BACKUP_BUCKET_NAME = "my-backup-bucket"
CLOUDFLARE_ACCOUNT_ID = "<YOUR_ACCOUNT_ID>"

[[r2_buckets]]
binding = "BACKUP_BUCKET"
bucket_name = "my-backup-bucket"

3. R2 API 資格情報をシークレットとして設定する

npx wrangler secret put R2_ACCESS_KEY_ID
npx wrangler secret put R2_SECRET_ACCESS_KEY

Cloudflare ダッシュボード ↗ の R2 > Overview > Manage R2 API Tokens で R2 API トークンを作成します。バックアップバケットに対する Object Read & Write 権限が必要です。

SDK はこれらの資格情報で署名付き URL を生成し、コンテナがバックアップアーカイブを R2 と直接やり取りできるようにします。セットアップの一連の手順はバックアップと復元ガイドを参照してください。

トラブルシューティング

バインディングが見つからない

エラー: TypeError: env.Sandbox is undefined

対処: wrangler.jsonc に Durable Objects バインディングがあることを確認してください。

{
	"durable_objects": {
		"bindings": [
			{
				"class_name": "Sandbox",
				"name": "Sandbox",
			},
		],
	},
}

[[durable_objects.bindings]]
class_name = "Sandbox"
name = "Sandbox"

マイグレーションがない

エラー: Durable Object が初期化されていない

対処: Sandbox クラスのマイグレーションを追加してください。

{
	"migrations": [
		{
			"new_sqlite_classes": ["Sandbox"],
			"tag": "v1",
		},
	],
}

[[migrations]]
new_sqlite_classes = [ "Sandbox" ]
tag = "v1"