Claude Platform Docs
Managed Agentsセルフホスト型サンドボックス

セッションごとに1つのサンドボックスを実行する

Kubernetes上のHelmチャート、スポーンスクリプト、またはSDKポーラーを使用して、各セッションに専用のセルフホスト型サンドボックスを割り当てます。

「sandbox-per-session」(セッションごとのサンドボックス)パターンでは、各セッションは新しいサンドボックスで実行され、サンドボックスごとに独自のファイルシステム、リソース制限、ネットワーク制御を持つことができます。他のパターンと比較するには、デプロイパターンを選択するを参照してください。

このパターンは次の3つの方法でセットアップできます。

  • Kubernetes上のHelmチャート: Anthropicのディスパッチャーがワークを取得し、クラスター上でセッションごとにPodを起動します。
  • スポーンスクリプト: ant CLIがワークを取得してスクリプトを呼び出し、スクリプトが任意のプラットフォーム上でサンドボックスを起動します。
  • SDKポーラー: 独自のコードがワークを取得し、サンドボックスを起動します。

Kubernetes上でサンドボックスを実行する以降のセクションは、スポーンスクリプトとSDKポーラーに適用されます。

Kubernetes上でサンドボックスを実行する

Anthropicは、Helmチャートcma-sandboxesとそのイメージを公開しています。このチャートは、独自のKubernetesクラスター上でセッションごとに1つのサンドボックスを実行します。チャートのディスパッチャーは環境のワークキューをポーリングし、各セッションに専用のPodを割り当てます。

  • 分離: 各Podは、チャートのネットワークポリシーの背後でgVisorの下で実行されます。Podは独自のファイルシステムとリソース制限を持ちます。環境キーを保持するのはディスパッチャーのみです。
  • セッションアフィニティ: セッション内のすべてのメッセージは、そのセッションのサンドボックスに送られます。セッションが30分間(チャートのsandbox.idleTimeout設定のデフォルト値)アイドル状態になると、そのPodは停止します。/workspaceボリュームはセッションが終了するまで残ります。次のメッセージが届くと、同じボリューム上でPodが起動します。
  • ウォームプール: Google Kubernetes Engine(GKE)以外では、チャートは新しいセッションのために2つのPodを待機状態に保ちます(チャートのsandbox.warmPoolSize設定のデフォルト値)。

サンドボックスPodはant CLIワーカーを実行します。デフォルトの同期設定でメモリストアをサポートしますが、カスタムツールはサポートしません。

チャートをインストールする

このチャートは、GKE、Amazon EKS、およびその他のクラスターで動作します。インストールする前に、以下をセットアップしてください。

  • クラスター内: Agent Sandboxコントローラー(GKEではAgent Sandboxアドオン)、gVisorを実行するノード、およびNetworkPolicyを適用するネットワークプラグイン。
  • 独自のnamespace内: Restricted Pod Security Standardのラベル、環境IDと環境キーを含むSecret、およびディスパッチャーのTLS証明書。

GitHub上のインストールガイドには、クラスターの種類ごとのセットアップ手順が記載されています。アップグレードとキーローテーションについても説明されています。

設定をcma-values.yamlとして保存します。このファイル内の3つの設定がないと、インストールは失敗します。

cma-values.yaml
platform: gke             # or eks, or generic for any other cluster
egress:
  # The chart already blocks the private ranges. List your other addresses
  # that sandboxes must not reach.
  clusterCIDRs:
    - 203.0.113.10/32     # your cluster's Kubernetes API endpoint
  cmaServer:
    public: true          # the Claude API has a public address

インストールガイドには、GKE Autopilotでのgke.dnsなど、クラスターに依存する設定が記載されています。また、egress.clusterIsPrivate: trueがegress.clusterCIDRsの代わりになる場合についても説明されています。

次に、チャートをインストールします。

helm install cma \
  oci://us-docker.pkg.dev/anthropic-public-registry/sandboxes/charts/cma-sandboxes \
  --version 0.1.0 \
  --namespace cma \
  -f cma-values.yaml \
  --wait

インストール後、インストールガイドに記載されているプリフライトチェックを実行してください。

サンドボックスイメージにツールを追加する

公開されているサンドボックスイメージは、bash、curl、jq、およびant CLIを含むAlpine Linuxです。チャートはこのイメージを読み取り専用のルートファイルシステムかつ非rootユーザーとして実行するため、エージェントはセッション中にパッケージをインストールできません。

PythonやGitなど、エージェントにより多くのツールを提供するには、リリースのタグでリポジトリから両方のイメージをビルドします。コマンドはインストールガイドのInstallセクションに記載されています。イメージをcma-dispatcherおよびcma-sandboxとしてレジストリにプッシュし、チャートのバージョンをタグとして付けます。次に、image.registryをそのレジストリに設定します。イメージダイジェストを固定する場合は、独自のイメージのダイジェストを使用してください。

ネットワークエグレスを制限する

デフォルトでは、チャートのネットワークポリシーにより、サンドボックスはパブリックIPv4インターネットに到達できます。プライベートアドレス範囲、クラウドメタデータサーバー、およびegress.clusterCIDRs内のアドレスはブロックされます。プロンプトインジェクションを受けたエージェントは、読み取った内容をサンドボックスが到達できる任意のアドレスに送信できます。詳細は、インストールガイドのNetwork egressを参照してください。

  • Dataplane V2を使用するGKE: egress.mode: fqdnGkeを設定すると、接続をegress.fqdnGke.hosts内のホストのポート443に制限できます。api.anthropic.comをこのリストに残し、エージェントのコマンドが必要とするすべてのホストを追加してください。デフォルトとは異なり、このモードにはブロックされる範囲のリストがありません。リストされたホスト名が解決される任意のアドレスを許可するため、DNSを信頼できるホストのみをリストしてください。それでも、サンドボックスはDNSルックアップ内でデータを外部に送信できます。
  • その他のクラスターおよびDataplane V2を使用しないGKE: デフォルトが唯一のモードです。
  • すべてのクラスター: ネットワークポリシーは、クラスター自身のノードがリッスンするポートをカバーしません。インストールガイドのNode isolation you ownを参照してください。

スポーンスクリプトでサンドボックスを起動する

ホスト上のポーラーがワークを取得し、「work item」(ワークアイテム)ごとにスクリプトを1回呼び出します。スクリプトはその1つのセッション用のサンドボックスを起動します。

  1. サンドボックスイメージをビルドする

    antをインストールし、ant beta:worker runをエントリポイントとして設定します。サンドボックスが起動すると、環境変数からセッションの詳細を読み取り、そのセッションを処理して終了します。ベースイメージは/bin/bashを提供する必要があります。ビルドではantのダウンロードにのみcurlを使用します。

    Dockerfile
    FROM your-base-image
    ARG ANT_VERSION=2.11.0
    ARG TARGETARCH
    RUN ARCH=$([ "$TARGETARCH" = "arm64" ] && echo arm64 || echo amd64) && \
        curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${ANT_VERSION}/ant_${ANT_VERSION}_linux_${ARCH}.tar.gz" \
          | tar -xz -C /usr/local/bin ant
    WORKDIR /workspace
    VOLUME /workspace
    ENTRYPOINT ["ant", "beta:worker", "run"]
  2. スポーンスクリプトを書く

    スクリプトはセッションの詳細を新しいサンドボックスに転送します。ポーラーホスト上にjqが必要です。

    spawn.sh
    #!/bin/bash
    # spawn.sh: 取得したワークアイテムごとに1回呼び出されます
    # 取得したワークアイテムは、stdin経由でJSONとして渡されます。
    ANTHROPIC_WORK_SECRET="$(jq -r '.secret // empty')"
    export ANTHROPIC_WORK_SECRET
    mkdir -p "/host/outputs/$ANTHROPIC_SESSION_ID"
    exec docker run --rm \
      -e ANTHROPIC_SESSION_ID -e ANTHROPIC_ENVIRONMENT_KEY \
      -e ANTHROPIC_WORK_ID -e ANTHROPIC_ENVIRONMENT_ID -e ANTHROPIC_BASE_URL \
      -e ANTHROPIC_WORK_SECRET \
      -v "/host/outputs/$ANTHROPIC_SESSION_ID":/workspace \
      your-image

    ポーラーはANTHROPIC_WORK_ID、ANTHROPIC_ENVIRONMENT_ID、ANTHROPIC_SESSION_ID、ANTHROPIC_ENVIRONMENT_KEYを設定します。ANTHROPIC_BASE_URLは、ポーラーのホストで設定した場合にのみスクリプトに渡されます。スクリプトは、標準入力上のワークアイテムのJSONからANTHROPIC_WORK_SECRETを読み取ります。環境変数を参照してください。

    /host/outputsは任意に選択するホストディレクトリです。これを/workspaceにマウントすると、サンドボックスの終了後にセッションの成果物を取り出せます。このマウントには、ダウンロードされたskills/ツリーや中間ファイルも含まれます。

  3. ポーラーを起動する

    ant beta:worker poll --on-work ./spawn.sh

ワークアイテムのシークレットを転送する

取得した各ワークアイテムは、Anthropicがそのセッションに対して発行するsecretを持つことがあります。セッションを実行するワーカーは、メモリストアをマウントするためにこれを必要とします。

1つのプロセス内でセッションを取得して実行するワーカーは、シークレットを自ら受け渡します。run()を使用するEnvironmentWorkerはそのようなワーカーの1つであり、--on-workなしのant beta:worker pollもその1つです。取得とワーカーの間に独自のコードが入る場合は、シークレットを自分で転送します。

ワークを取得する方法シークレットの受け取り方ワーカーへの渡し方
ant beta:worker poll --on-workスクリプトの標準入力上のワークアイテムJSONのsecretフィールドサンドボックスの環境内のANTHROPIC_WORK_SECRET
Python、TypeScript、またはGo SDKのwork.poller()取得した各ワークアイテムのsecretフィールドサンドボックスの環境内のANTHROPIC_WORK_SECRET、またはhandle_item()へのwork_secret引数

シークレットは、そのセッションを処理するサンドボックスにのみ渡し、決してログに記録しないでください。環境キーとの関係については、セキュリティモデルを参照してください。

SDKポーラーからサンドボックスを起動する

ant beta:worker poll --on-workの代わりに独自のコードからワークを取得するには、Python、TypeScript、またはGo SDKのポーラーwork.poller()を使用します。ポーラーはキューをポーリングして取得した各セッションを渡し、サンドボックスの起動は独自のコードで行います。

import asyncio
import os

from anthropic import AsyncAnthropic
from anthropic.types.beta.environments import BetaSelfHostedWork

SANDBOX_ENV = (
    "ANTHROPIC_ENVIRONMENT_ID",
    "ANTHROPIC_ENVIRONMENT_KEY",
    "ANTHROPIC_WORK_ID",
    "ANTHROPIC_SESSION_ID",
    "ANTHROPIC_WORK_SECRET",
    "ANTHROPIC_BASE_URL",  # forwarded only when set on this host
)


async def launch_container(work: BetaSelfHostedWork) -> None:
    print(f"claimed session {work.data.id}")
    # `docker run` を独自のサンドボックスランチャーに置き換えてください。環境
    # キー(APIキーは絶対に渡さないでください)とワークアイテムのセッションごとのシークレットを転送します。内部の
    # ワーカーはセッションのメモリストアをマウントするためにシークレットを必要とします。
    env = os.environ | {
        "ANTHROPIC_WORK_ID": work.id,
        "ANTHROPIC_SESSION_ID": work.data.id,
        "ANTHROPIC_WORK_SECRET": work.secret or "",
    }
    forward = [arg for name in SANDBOX_ENV for arg in ("-e", name)]
    launcher = await asyncio.create_subprocess_exec(
        "docker", "run", "--rm", "--detach", *forward, "your-image", env=env
    )
    await launcher.wait()


async def main() -> None:
    environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
    environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
    async with AsyncAnthropic(auth_token=environment_key) as client:
        async for work in client.beta.environments.work.poller(
            environment_id=environment_id,
            environment_key=environment_key,
            auto_stop=False,  # the launched sandbox owns the stop call
        ):
            await launch_container(work)


asyncio.run(main())

サンドボックス内でSDKワーカーを実行する

サンドボックスがカスタムツールを提供する必要がある場合や、デフォルト以外のメモリ同期設定を使用する必要がある場合は、ant beta:worker runエントリポイントをSDKエントリポイントに置き換えます。このエントリポイントはEnvironmentWorkerを構築し、handle_item()を呼び出します。これは、スポーンスクリプトが転送するのと同じANTHROPIC_*変数を読み取ります。

import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker


async def main() -> None:
    async with AsyncAnthropic(
        auth_token=os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
    ) as client:
        worker = EnvironmentWorker(client, workdir="/workspace")
        # 引数なしの場合、handle_item() はスポーンスクリプトが転送した
        # ANTHROPIC_* 変数(ANTHROPIC_WORK_SECRET を含む)を読み取ります。
        task = asyncio.create_task(worker.handle_item())
        # コンテナ停止時にタスクをキャンセルすると、ワーカーは終了前に
        # 変更されたメモリファイルをアップロードし、ストアディレクトリを削除できます。
        loop = asyncio.get_running_loop()
        for signum in (signal.SIGINT, signal.SIGTERM):
            loop.add_signal_handler(signum, task.cancel)
        with contextlib.suppress(asyncio.CancelledError):
            await task


asyncio.run(main())

セッション用のファイルをステージングする

Anthropicは、セルフホスト型サンドボックスにファイルやGitHubリポジトリをマウントしません。セッション固有のファイルを利用可能にするには、次の手順を実行します。

  1. S3パスやコミットSHAなどのファイル参照を、セッションのmetadataフィールドで渡します。
  2. スポーンスクリプトまたは--on-workハンドラー内で、セッションを取得し(GET /v1/sessions/{session_id})、metadataを読み取ります。取得したワークアイテムにはセッションIDが含まれますが、メタデータは含まれません。
  3. ツールが実行される前に、ファイルを作業ディレクトリにステージングします。

cURLのサンプルは、ANTHROPIC_AUTH_TOKENからアクセストークンを読み取ります。トークンを入手するには、フェデレーションのセットアップの説明に従って、デフォルトのworkspace:developerスコープでWorkload Identity Federationをセットアップします。次に、ワークロードからの認証に示すように、ワークロードのIDトークンをアクセストークンと交換します。ANTHROPIC_AUTH_TOKENはフェデレーション設定よりも優先されるため、cURLのサンプルを実行するシェルでのみ設定してください。認証には、クイックスタートのAPIキーなど、APIが受け付けるその他の認証情報が記載されています。

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    metadata={"input_file": "s3://my-bucket/data.csv"},
)

次のステップ

キューの深さを確認し、セッションとワーカーを正常に停止し、一般的な障害を修正します。

このページは役に立ちましたか?