Claude Agent SDKのサンドボックス：各タスクを専用のワークスペースで実行する

Claude Agent SDKのサンドボックスは、SDKのエージェントプロセス、ツール、作業ファイルを実行・使用する環境です。 SDKはClaude CLIのサブプロセスを起動します。そのプロセスに独立したVMやコンテナを割り当てると、アクセスできるファイルと認証情報、タスク終了時の処理を定義できます。作業ディレクトリを設定するだけでは、この境界は作れません。Anthropicのホスティングガイド

独立したジョブには、タスクごとに1つのワークスペースを使用します。複数のリクエストにまたがるセッションでは、ワークスペースを保持するか、再開に必要な状態を永続化します。認証、タスクの所有者情報、スケジューリングは、エージェントのマシン外にあるコーディネーターで管理します。

私たちはLizardを開発しています。このガイドでは、Lizard Sandboxesを使った小規模な設定例を示し、ホスティングの選択肢を比較します。APIとコマンドは2026年11月4日に確認しました。新しいSDKの例はドキュメントと照合してレビューしましたが、クラウドサンドボックスからAnthropicに接続して実行してはいません。

ホストに必要なもの

Agent SDKには、ランタイム、CLIサブプロセス、作業ディレクトリ、モデルサービスへのアクセスが必要です。サブプロセスは、SDK自体より多くのメモリ、CPU、ディスクを使うツールを起動する場合もあります。タスクに合わせてワークスペースのサイズを決めてください。数個のファイルを読む場合と、リポジトリをビルドしたりブラウザを操作したりする場合では、必要なサイズが異なります。

ローカルディレクトリはアプリケーションの状態を分けますが、オペレーティングシステム上で同じアクセス権を持つプロセスは、他のディレクトリにもアクセスできます。互いに関係のないユーザーには、そのリスクに合った分離境界を使用してください。Anthropicの安全なデプロイのガイドでは、分離と認証情報について説明しています。

ホスティング先を選ぶ

Lizard Sandboxesは、独自のカーネルを持つFirecracker microVM、用意済みのテンプレート、コマンド実行、ファイル転送を提供します。固定のマシンサイズに収まるCPUタスクに適しています。Lizardは、サンドボックス用のGPUインスタンスや、任意のDockerfileに基づくサンドボックステンプレートを提供していません。Lizard Sandboxes

E2Bは、Linuxサンドボックス、テンプレート、コード実行APIを提供します。Daytonaは、ワークスペースツールと複数のランタイムクラスを提供します。Modalは柔軟に拡張できるCPUリソースとGPUワークフローをサポートし、ランタイムごとの制約があります。DockerやKubernetesでデプロイする場合は、自分のインフラを制御できますが、容量、分離、クリーンアップも自分で管理します。E2B、Daytona、Modal

SDKは、必要なランタイムとサブプロセスのサポートを備えたホストで実行でき、特定のサンドボックスベンダーを必要としません。実際のワークロードで、依存関係、ネットワークアクセス、終了時の動作、メモリ使用量を確認してください。

小さな読み取り専用のSDKタスクから始める

この例では、ローカルのプロジェクトファイルを読み、Claudeに要約を依頼します。エージェントが使えるツールはRead、Glob、Grepのみです。無制限のBash実行や権限のバイパスは必要ありません。

Lizardのプロジェクトとサインイン済みのLizard CLIに加え、モデル呼び出し用のAnthropic APIキーが必要です。LizardのコンピューティングとAnthropicの使用量は別々に課金されます。現在の手順に従ってCLIをインストールしてください。

1. Smallのワークスペースを作成する

プロジェクトのプレースホルダーを置き換え、返されたサンドボックスIDをSBにコピーします。

lizard sandbox create --project YOUR_PROJECT_ID \
  --template claude --size small --timeout 3600000 --json
SB=YOUR_SANDBOX_ID
lizard sandbox exec "$SB" -- mkdir -p /workspace/agent

有効期間を明示的に1時間に設定しています。CLIのデフォルトは5分であり、コマンドを実行しても期限はリセットされません。ジョブに合った期限を設定し、期限切れになる前に出力を保存してください。サンドボックスCLI

2. SDKランナーをローカルに保存する

次のコードでsummarize.mjsを作成します。

import { query } from '@anthropic-ai/claude-agent-sdk';

if (!process.env.ANTHROPIC_API_KEY) {
  throw new Error('Set ANTHROPIC_API_KEY inside the task environment');
}

let completed = false;
for await (const message of query({
  prompt: 'Read README.md and summarize the project in two sentences.',
  options: {
    cwd: '/workspace/agent',
    settingSources: [],
    tools: ['Read', 'Glob', 'Grep'],
    allowedTools: ['Read', 'Glob', 'Grep'],
    permissionMode: 'dontAsk',
    maxTurns: 6,
  },
})) {
  if (message.type !== 'result') continue;
  if (message.subtype !== 'success' || message.is_error) {
    throw new Error(`Agent failed: ${message.subtype}`);
  }
  completed = true;
  console.log(message.result);
}
if (!completed) throw new Error('Agent ended without a successful result');

toolsは使用可能な組み込みツールを選択します。allowedToolsは呼び出しを事前承認しますが、それだけで完全なツールの許可リストになるわけではありません。dontAskは権限のないリクエストを拒否します。少ないターン数の上限は、この例のエージェントのループを制限しますが、クラウド支出の総額に上限を設けるものではありません。Agent SDKリファレンス

スクリプトと同じ場所に小さなREADME.mdを作成し、両方のファイルをアップロードします。

lizard sandbox files put "$SB" ./summarize.mjs /workspace/agent/summarize.mjs
lizard sandbox files put "$SB" ./README.md /workspace/agent/README.md
lizard sandbox shell "$SB"

3. ワークスペース内でインストールして実行する

サンドボックスのBashシェルで実行します。

cd /workspace/agent
npm init -y
npm install --save-exact @anthropic-ai/claude-agent-sdk
read -rsp 'Anthropic API key: ' ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY
node summarize.mjs
unset ANTHROPIC_API_KEY

期待する結果は、標準出力に短い要約が表示され、終了ステータスが0になることです。認証情報の不足、操作の拒否、ターン数の上限到達があれば、実行は失敗するはずです。生成したロックファイルを保持し、この例を再現可能な環境にする際はnpm ciを使用してください。

プロンプトで入力することで、キーがシェルの履歴に残るのを防ぎます。ただし、タスクの実行中は、キーがエージェントの環境内に存在します。信頼できない処理を実行するサービスでは、サンドボックスの外で認証情報を付加する送信用プロキシを検討してください。SDKの認証とホスティング

4. 必要なものをエクスポートしてから一時停止する

サンドボックスのシェルを終了し、lizard sandbox files getで出力ファイルを取得します。結果を保存したら、次を実行します。

lizard sandbox pause "$SB"

最終状態がpausedであることを確認します。一時停止が成功すると、コンピューティングの課金が停止し、ワークスペースの状態を保持します。Persistent Volumesのストレージは別途課金されます。この例のローカルディスクは、パスが/workspaceで始まるだけで永続ストレージになるわけではありません。永続化、Persistent Volumes

ランナーの周辺に本番運用の処理を追加する

エージェントを起動する前に、各リクエストをタスクレコードに記録します。所有者、サンドボックスID、ステータス、期限、出力先を保存します。コーディネーターを通じて進捗をストリーミングし、クライアントの接続とは独立して最終結果を保持します。

キャンセルとクリーンアップは別々の処理で扱います。クライアントが切断しても、有用な作業をキャンセルする必要はありません。キャンセルしたタスクのマシンを、見えないところで稼働させ続けてはいけません。一時的な障害の後はクリーンアップを再試行し、タスクレコードとサンドボックスの実際の状態を照合して整合させます。

セッションでは、セッションIDと、必要な会話履歴およびファイルの状態を保存します。IDだけを含むデータベースの行では、失われたワークスペースのファイルを復元できません。Anthropicは、セッションの保存と作業ディレクトリ内のファイルについて、別々に説明しています。セッション、ホスティング時の状態管理

再利用するテンプレートの状態に、ユーザーの認証情報や非公開のタスクファイルを含めないでください。互いに関係のないタスクごとに、そのクリーンな状態に戻します。確実にリセットできることを確認せずに、あるユーザーの一時停止中のマシンを別のユーザーのワークスペースにしてはいけません。

ワークスペースのコスト

LizardのSmallは、稼働1時間あたり$0.0162です。合計100時間の稼働で$1.62のコンピューティングを使用しますが、新規Proアカウントでも月額最低料金は$19で、$19分の使用量を含みます。モデルの呼び出し、Persistent Volumes、その他のリソースには、それぞれ予算が必要です。Lizardの料金

ProはSmallサンドボックスの同時実行数20、1日あたりの新規起動数400をサポートし、1分および1時間あたりの起動数にも上限があります。Pro 5xは$99で$99分の使用量を含み、最大110のSmallサンドボックスをサポートします。Pro 20xは$499で$499分の使用量を含み、最大600をサポートします。同時実行数が増えても、各タスクが同じ速度で完了するとは限りません。現在の制限

パッケージのインストール、モデルの応答待ち、出力の転送を含めた実行時間全体を測定してください。リクエストの間にワークスペースを一時停止する場合は、コーディネーターをその外に置く必要があります。一時停止したプロセスは、自分自身を再開するためのリクエストを受信できません。

Claude Agent SDKの作業ディレクトリはサンドボックスですか？ いいえ。cwdはプロセスの作業場所を選択します。そのディレクトリ外へのアクセスを定義するには、オペレーティングシステムの制御や、独立したコンテナまたはVMを使用してください。

SDKサービスを書く代わりにClaude Codeから始められますか？ はい。単一のコーディングタスクには、Claude Codeのサンドボックスガイドで、より短いCLIワークフローを紹介しています。アプリケーションがエージェントのメッセージ、ツールのポリシー、セッションの動作をコードで管理する必要がある場合は、SDKを使用してください。