セルフホスト型サンドボックス

デフォルトでは、Managed AgentsはAnthropic管理のクラウドサンドボックス内でツールとコードを実行します。セルフホスト型サンドボックスでは、オーケストレーションはAnthropic側に残しつつ、ツール実行をユーザーが管理するインフラストラクチャに移すため、エージェントのコード、ファイルシステム、ネットワーク送信がユーザーの環境から外に出ることはありません。

ツール実行はユーザーのホスト上にとどまります。エージェントが読み書きするファイルシステム、起動するプロセス、到達可能なネットワークはすべてユーザーの管理下にあります。ツールの入力と出力は引き続きAnthropicのコントロールプレーン（Claudeが実行される場所）に送信されるため、モデルは結果を確認し、次に何をすべきかを判断できます。データフローの境界の詳細については、セキュリティモデルを参照してください。

クラウド環境との違い

セルフホスティングは、エージェントがネットワーク境界外に出せないデータを操作する必要がある場合、パブリックにルーティングできない内部サービスにアクセスする必要がある場合、または組織独自のコンプライアンスおよび監査管理下で実行する必要がある場合に適しています。

Zero Data RetentionおよびHIPAA BAAの適格性については、APIとデータ保持を参照してください。

MCPトンネルと組み合わせる場合

セルフホスティングはエージェントのコードがどこで実行されるかを制御します。MCPトンネルはAnthropicがユーザーのネットワーク内のMCPサーバーにどのように到達するかを制御します。これらは独立しています。Anthropicのクラウドサンドボックスで実行されているセッションでもトンネル経由でプライベートMCPサーバーに到達でき、セルフホスト型セッションでもトンネル経由またはパブリックのMCPサーバーのいずれかを使用できます。実行とツールアクセスの両方をユーザーの境界内にとどめたい場合は、両方を使用してください。

環境ワーカー

環境ワーカーは、ユーザー自身のインフラストラクチャ上で実行するプロセスです。Anthropicからツール実行リクエストを受信し、ローカルで実行します。self_hosted環境はワークキューとして機能します。セッションがこの環境に割り当てられると、Anthropicはそのセッションをワークアイテムとしてキューに追加します。ワーカーはそのキューからワークアイテムを取得し、それぞれに対して実行コンテキストを生成し、エージェントのスキル（エージェントにドメイン固有の専門知識を与える、再利用可能なファイルシステムベースのリソース）をダウンロードし、ツール呼び出しを実行して、結果を返送します。

ワークアイテムは環境のキューをポーリングすることで取得されます。継続的にポーリングする常時稼働ワーカー、またはsession.status_run_startedで起動してポーリングを開始するWebhookトリガー型ハンドラーのいずれかを使用します。

CLIとSDKの両方に、事前構築済みのワーカーが同梱されています。ant CLIは常時稼働パターンのみをサポートし、SDKは常時稼働とWebhookトリガー型の両方をサポートします。どちらも設定可能です。CLIフラグについてはリファレンスのセルフホスト型ワーカーを、SDKオプションについてはこのページのSDKヘルパーを参照してください。より細かい制御が必要な場合は、Environments Workエンドポイントを直接呼び出して独自のワーカーを実装してください。Claude Platform on AWSでは、GET /v1/environments/{id}/workリストエンドポイントとそのSDK相当機能は現在利用できません。その他のワークエンドポイント（poll、ack、heartbeat、stop、結果の送信、アイテムごとのget、stats）は通常どおり動作します。

サンドボックスのファイルシステム

• /workspace： ツール実行とスキルダウンロードのシステムデフォルト作業ディレクトリです。CLIの--workdirフラグはデフォルトでカレントディレクトリになります。システムデフォルトに合わせるには--workdir /workspaceを渡してください。スキルは<workdir>/skills/<name>/にダウンロードされます。別の作業ディレクトリを使用する場合は、Claudeがスキルファイルを見つけられるようにエージェントのシステムプロンプトを更新してください。
• /mnt/session/outputs： ワーカーハーネスは、最終成果物をここに書き込むようClaudeに指示します。サンドボックスモードでは、セッション終了後に出力を取得できるように、このパスにホストディレクトリをマウントしてください。インプロセスモードでは、ワーカーのファイルツールは代わりに作業ディレクトリ配下に書き込むため、このパスは適用されません。

事前準備

以下が必要です。

• 既存のエージェント。 まだない場合は、まずクイックスタートを完了し、そのエージェントIDを控えておいてください。
• Linuxホスト（/bin/bashがその正確なパスに存在すること）。TypeScript SDKは追加でunzip、tar、Node.js 22以降が必要です。Python SDKはアーカイブ展開に標準ライブラリを使用するため、追加のバイナリ要件はありません。これらの依存関係は固定パスで解決され、PATHのオーバーライドは考慮されません。
• ワーカーホスト上の**ant CLIまたはAnthropic SDK**（Python、TypeScript、またはGo）。
• 2つの認証情報： 環境キー（以下の手順で生成）はワーカーをそのキューに対して認証します。Claude APIキーは、ワーカーホストの外部からセッションを作成し、キュー統計を読み取るために使用します。

ワーカーを実行する

最もシンプルなセットアップには常時稼働を選択してください。長時間実行されるプロセスがキューを継続的にポーリングし、アウトバウンドHTTPSのみが必要です。アイドル状態のポーラーを実行したくない場合はWebhookトリガー型を選択してください。これにはAnthropicが到達可能なWebhookエンドポイントが必要です（エンドポイントのセットアップと署名検証についてはWebhookを参照してください）。

SDKヘルパー

SDKは、異なる制御レベルの3つのヘルパーを提供します。EnvironmentWorkerはほとんどのユースケースをカバーします。セッションごとに独自のプロセスを起動する必要がある場合や、すでに取得済みのセッションに対してツールを実行する必要がある場合は、より低レベルのヘルパーを使用してください。

• EnvironmentWorker： すぐに使えるワーカーです。ポーリング、セットアップ、実行をエンドツーエンドで処理します。
  • .run()：無期限に実行され、セッションが到着するたびに処理します。SIGTERMで正常に終了します。
  • .handle_item()：保留中のセッションを1つ取得し、処理して終了します。
• work.poller()： ユーザーに代わってワークキューをポーリングし、取得した各セッションを渡します。セッションごとに何を行うかを自分で決定したい場合（たとえば、インプロセスでツールを実行するのではなくサンドボックスを起動する場合）に使用します。
  • drain：新しいワークを待つのではなく、キューが空になったらポーリングを停止するかどうか。
  • block_ms：ワークが到着するまで待機する時間（ミリ秒単位）。1から999の間である必要があります（ポーリングごとの待機時間。ヘルパーは自動的に再ポーリングします）。ノンブロッキングチェックにはnull（PythonではNone、Goではparam.Null[int64]()）を渡します。パラメータを省略すると、デフォルトの999ミリ秒のロングポーリングが使用されます。

セッションごとに独自のプロセスを起動したい場合（たとえば、取得した各セッションに対してサンドボックスを起動する場合）は、ワークポーラーを直接使用します。

**AgentToolContextはツール呼び出しの実行コンテキストです。作業ディレクトリとパスポリシーを定義し、コンテキストマネージャーとして使用する場合はオプションでセッションのスキルをダウンロードします。beta_agent_toolset_20260401(env)**はAgentToolContextを受け取り、標準のツール実装（bash、read、write、edit、glob、grep）を返します。

EnvironmentWorkerを使用する場合： 両方とも自動的に管理されます。ツールリストをカスタマイズするにはtoolsファクトリを渡します。

EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])

work.poller()とtool_runner()を使用する場合： client.beta.sessions.events.tool_runner()にtoolsとしてツールリストを渡します。そのリストを構築するには、AgentToolContextを自分でセットアップし、beta_agent_toolset_20260401(env)を呼び出します。

ワーカーが接続されていることを確認する

別のシェルから、（環境キーではなく）Claude APIキーを使用して、workers_pollingが1以上であることを確認します。

ant beta:environments:work stats --environment-id "$ANTHROPIC_ENVIRONMENT_ID"

workers_pollingが0のままの場合、ワーカーがキューに到達していません。ワーカーホストでANTHROPIC_ENVIRONMENT_KEYとANTHROPIC_ENVIRONMENT_IDが設定されていることを確認してください。完全な統計レスポンスと他の言語の例については、キューの深さを読み取るを参照してください。

セッションを開始する

ワーカーが実行されたら、その環境をターゲットとするセッションを作成します。セッションは環境のワークキューに入り、ワーカーが取得するまでそこで待機します。ワーカーが接続されていない場合、セッションは失敗するのではなくキューに残ります。

Anthropicは、セルフホスト型サンドボックスにファイルやGitHubリポジトリをマウントしません。セッション固有のファイルを利用可能にするには、セッションのmetadataフィールドにファイル参照（S3パスやコミットSHAなど）を渡します。起動スクリプトまたは--on-workハンドラーは、取得したワークアイテムからそのメタデータを（Environments Workエンドポイント経由で）読み取り、ツール実行が開始される前にファイルを作業ディレクトリにステージングします。

CLIフラグの完全なリストについてはリファレンスのセルフホスト型ワーカーを、SDKヘルパーオプションについてはSDKヘルパーを参照してください。

監視と運用

これらの呼び出しは、Claude APIキーで認証された監視または運用ツールから実行し、ワーカーフリートを監視および管理します。取得とキープアライブのループはワーカーヘルパー内で処理されるため、これらのエンドポイントを直接呼び出す必要はありません。

キューの深さを読み取る

work.statsは環境のキュー状態を返します。

• depthは、取得待ちのアイテム数です。この値に基づいてワーカーフリートをスケーリングしたり、バックログに対してアラートを設定したりします。
• pendingは、ワーカーが取得して現在処理中のアイテム数です。
• oldest_queued_atは、キュー内の最も古いアイテムのタイムスタンプです。キューが空の場合はnullです。
• workers_pollingは、過去30秒間にポーリングしたワーカーの数です。これを稼働状態のアラートに使用します。

{
  "type": "work_queue_stats",
  "depth": 0,
  "pending": 0,
  "oldest_queued_at": null,
  "workers_polling": 0
}

セッションを正常に停止する

work.stopを使用して、特定のセッションを処理しているワーカーに正常なシャットダウンを要求します。ワーカーは処理中のツール呼び出しを完了し、最終ステータスを送信して、セッションを解放します。現在のツール呼び出しの完了を待たずに即座に中断するには、リクエストボディにforce: trueを渡します。

これらの呼び出しはワーカーホストではなく運用ツールから実行されるため、ANTHROPIC_WORK_IDは自動的には設定されません。以下の例を実行する前に、対象のワークアイテムのIDに設定してください。

次のステップ