Claude Platform Docs
Managed AgentsSelbst gehostete Sandboxes

Eine Sandbox pro Sitzung ausführen

Gib jeder Sitzung ihre eigene selbst gehostete Sandbox mit dem Helm-Chart auf Kubernetes, einem Spawn-Skript oder dem SDK-Poller.

Beim Muster „sandbox-per-session“ (Sandbox pro Sitzung) läuft jede Sitzung in einer neuen Sandbox, die ihr eigenes Dateisystem, eigene Ressourcenlimits und eigene Netzwerkkontrollen haben kann. Um es mit den anderen Mustern zu vergleichen, siehe Ein Bereitstellungsmuster wählen.

Du kannst es auf drei Arten einrichten:

  • Helm-Chart auf Kubernetes: Der Dispatcher von Anthropic beansprucht Arbeit und startet für jede Sitzung einen Pod auf deinem Cluster.
  • Spawn-Skript: Die ant CLI beansprucht Arbeit und ruft dein Skript auf, das auf einer beliebigen Plattform eine Sandbox startet.
  • SDK-Poller: Dein eigener Code beansprucht Arbeit und startet die Sandbox.

Die Abschnitte nach Sandboxes auf Kubernetes ausführen gelten für das Spawn-Skript und den SDK-Poller.

Sandboxes auf Kubernetes ausführen

Anthropic veröffentlicht ein Helm-Chart, cma-sandboxes, und dessen Images. Das Chart führt eine Sandbox pro Sitzung auf deinem eigenen Kubernetes-Cluster aus. Sein Dispatcher fragt die Work-Queue der Umgebung ab und gibt jeder Sitzung einen eigenen Pod:

  • Isolation: Jeder Pod läuft unter gVisor hinter den Netzwerkrichtlinien des Charts. Er hat sein eigenes Dateisystem und eigene Ressourcenlimits. Nur der Dispatcher besitzt den Umgebungsschlüssel.
  • Session affinity (Sitzungsaffinität): Jede Nachricht in einer Sitzung geht an die Sandbox dieser Sitzung. Nachdem die Sitzung 30 Minuten lang im Leerlauf geblieben ist (der Standardwert der Chart-Einstellung sandbox.idleTimeout), stoppt ihr Pod. Ihr /workspace-Volume bleibt bestehen, bis die Sitzung endet. Die nächste Nachricht startet einen Pod auf demselben Volume.
  • Warm pool (vorgewärmter Pool): Außer auf Google Kubernetes Engine (GKE) hält das Chart zwei Pods für neue Sitzungen bereit (der Standardwert der Chart-Einstellung sandbox.warmPoolSize).

Sandbox-Pods führen den ant-CLI-Worker aus. Sie unterstützen Memory Stores mit den Standard-Synchronisierungseinstellungen und unterstützen keine benutzerdefinierten Tools.

Das Chart installieren

Das Chart läuft auf GKE, Amazon EKS und anderen Clustern. Richte Folgendes ein, bevor du es installierst:

  • Im Cluster: Den Agent Sandbox-Controller (auf GKE das Agent-Sandbox-Add-on), Nodes, die gVisor ausführen, und ein Netzwerk-Plugin, das NetworkPolicy durchsetzt.
  • In deinem eigenen Namespace: Labels für den Restricted Pod Security Standard, ein Secret mit der Umgebungs-ID und dem Umgebungsschlüssel sowie das TLS-Zertifikat des Dispatchers.

Die Installationsanleitung auf GitHub enthält die Einrichtungsschritte für jede Art von Cluster. Sie behandelt außerdem Upgrades und Schlüsselrotation.

Speichere deine Einstellungen als cma-values.yaml. Ohne die drei Einstellungen in dieser Datei schlägt die Installation fehl:

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

Die Installationsanleitung listet die Einstellungen auf, die von deinem Cluster abhängen, wie etwa gke.dns auf GKE Autopilot. Sie gibt außerdem an, wann egress.clusterIsPrivate: true an die Stelle von egress.clusterCIDRs tritt.

Installiere dann das Chart:

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

Führe nach der Installation die Preflight-Prüfung aus, die die Installationsanleitung beschreibt.

Tools zum Sandbox-Image hinzufügen

Das veröffentlichte Sandbox-Image ist Alpine Linux mit bash, curl, jq und der ant CLI. Das Chart führt es mit einem schreibgeschützten Root-Dateisystem und als Nicht-Root-Benutzer aus, sodass ein Agent während einer Sitzung keine Pakete installieren kann.

Um deinen Agenten weitere Tools wie Python oder Git zu geben, baue beide Images aus dem Repository beim Tag des Releases. Der Abschnitt „Install“ der Installationsanleitung enthält die Befehle. Pushe die Images als cma-dispatcher und cma-sandbox in deine Registry, mit der Version des Charts als Tag. Setze dann image.registry auf diese Registry. Wenn du Image-Digests festlegst, verwende die Digests deiner eigenen Images.

Ausgehenden Netzwerkverkehr einschränken

Standardmäßig erlauben die Netzwerkrichtlinien des Charts einer Sandbox, das öffentliche IPv4-Internet zu erreichen. Sie blockieren private Adressbereiche, den Cloud-Metadatenserver und die Adressen in egress.clusterCIDRs. Ein durch Prompt-Injection manipulierter Agent kann das, was er liest, an jede Adresse senden, die seine Sandbox erreichen kann. Network egress (ausgehender Netzwerkverkehr) in der Installationsanleitung enthält die Details.

  • GKE mit Dataplane V2: Setze egress.mode: fqdnGke, um Verbindungen auf Port 443 der Hosts in egress.fqdnGke.hosts zu beschränken. Behalte api.anthropic.com in dieser Liste und füge jeden Host hinzu, den die Befehle deiner Agenten benötigen. Anders als der Standardmodus hat dieser Modus keine Liste blockierter Bereiche. Er erlaubt jede Adresse, in die der Name eines aufgelisteten Hosts aufgelöst wird, also liste nur Hosts auf, deren DNS du vertraust. Eine Sandbox kann weiterhin Daten innerhalb von DNS-Abfragen nach außen senden.
  • Andere Cluster und GKE ohne Dataplane V2: Der Standardmodus ist der einzige Modus.
  • Jeder Cluster: Netzwerkrichtlinien decken die Ports nicht ab, auf denen die eigenen Nodes des Clusters lauschen. Siehe Node isolation you own in der Installationsanleitung.

Sandboxes mit einem Spawn-Skript starten

Ein Poller auf dem Host beansprucht Arbeit und ruft dein Skript einmal für jedes Arbeitselement auf. Das Skript startet eine Sandbox für genau diese eine Sitzung.

  1. Das Sandbox-Image bauen

    Installiere ant und setze ant beta:worker run als Entrypoint. Wenn eine Sandbox startet, liest sie die Sitzungsdetails aus Umgebungsvariablen, verarbeitet diese Sitzung und beendet sich. Das Basis-Image muss /bin/bash bereitstellen; der Build verwendet curl nur, um ant herunterzuladen.

    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. Das Spawn-Skript schreiben

    Das Skript leitet die Sitzungsdetails in eine neue Sandbox weiter. Es benötigt jq auf dem Poller-Host.

    spawn.sh
    #!/bin/bash
    # spawn.sh: wird einmal für jedes beanspruchte Arbeitselement aufgerufen
    # Das beanspruchte Arbeitselement kommt als JSON über stdin an.
    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

    Der Poller setzt ANTHROPIC_WORK_ID, ANTHROPIC_ENVIRONMENT_ID, ANTHROPIC_SESSION_ID und ANTHROPIC_ENVIRONMENT_KEY. ANTHROPIC_BASE_URL erreicht das Skript nur, wenn du die Variable auf dem Host des Pollers setzt. Das Skript liest ANTHROPIC_WORK_SECRET aus dem JSON des Arbeitselements auf der Standardeingabe. Siehe Umgebungsvariablen.

    /host/outputs ist ein Host-Verzeichnis, das du wählst. Wenn du es unter /workspace einbindest, kannst du die Ergebnisse der Sitzung abrufen, nachdem sich die Sandbox beendet hat. Die Einbindung erfasst außerdem den heruntergeladenen skills/-Baum und alle Zwischendateien.

  3. Den Poller starten

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

Das Secret des Arbeitselements weiterleiten

Jedes beanspruchte Arbeitselement kann ein secret enthalten, das Anthropic für diese Sitzung ausstellt. Der Worker, der die Sitzung ausführt, benötigt es, um Memory Stores einzubinden.

Ein Worker, der Sitzungen in einem einzigen Prozess beansprucht und ausführt, gibt das Secret selbst weiter. EnvironmentWorker mit run() ist ein solcher Worker, und ant beta:worker poll ohne --on-work ist ein weiterer. Wenn dein eigener Code zwischen dem Beanspruchen und dem Worker steht, leitest du das Secret weiter:

Du beanspruchst Arbeit mitDas Secret kommt an alsGib es an den Worker weiter als
ant beta:worker poll --on-workDas Feld secret des Arbeitselement-JSON auf der Standardeingabe deines SkriptsANTHROPIC_WORK_SECRET in der Umgebung der Sandbox
work.poller() des Python-, TypeScript- oder Go-SDKDas Feld secret jedes beanspruchten ArbeitselementsANTHROPIC_WORK_SECRET in der Umgebung der Sandbox oder das Argument work_secret für handle_item()

Gib das Secret nur an die Sandbox weiter, die diese Sitzung bedient, und protokolliere es niemals. Unter Sicherheitsmodell erfährst du, wie es mit dem Umgebungsschlüssel zusammenhängt.

Sandboxes aus dem SDK-Poller starten

Um Arbeit aus deinem eigenen Code statt mit ant beta:worker poll --on-work zu beanspruchen, verwende den Poller im Python-, TypeScript- oder Go-SDK: work.poller(). Er fragt die Queue ab und übergibt dir jede beanspruchte Sitzung, und du startest die Sandbox:

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}")
    # Ersetze `docker run` durch deinen eigenen Sandbox-Launcher. Leite den Umgebungsschlüssel
    # (niemals deinen API-Key) und das sitzungsspezifische Secret des Arbeitselements weiter: Der Worker
    # darin braucht das Secret, um die Memory Stores der Sitzung einzubinden.
    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())

Den SDK-Worker innerhalb der Sandbox ausführen

Ersetze den Entrypoint ant beta:worker run durch einen SDK-Entrypoint, wenn die Sandbox benutzerdefinierte Tools bereitstellen oder nicht standardmäßige Memory-Synchronisierungseinstellungen verwenden muss. Der Entrypoint erstellt EnvironmentWorker und ruft handle_item() auf, das dieselben ANTHROPIC_*-Variablen liest, die das Spawn-Skript weiterleitet.

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")
        # Ohne Argumente liest handle_item() die ANTHROPIC_*-Variablen, die das Spawn-
        # Skript weitergegeben hat, einschließlich ANTHROPIC_WORK_SECRET.
        task = asyncio.create_task(worker.handle_item())
        # Wird der Task beim Stoppen des Containers abgebrochen, kann der Worker
        # geänderte Memory-Dateien hochladen und die Store-Verzeichnisse vor dem Beenden entfernen.
        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())

Dateien für eine Sitzung bereitstellen

Anthropic bindet keine Dateien oder GitHub-Repositories in selbst gehostete Sandboxes ein. So stellst du sitzungsspezifische Dateien bereit:

  1. Übergib Dateireferenzen, etwa einen S3-Pfad oder einen Commit-SHA, im Feld metadata der Sitzung.
  2. Rufe in deinem Spawn-Skript oder --on-work-Handler die Sitzung ab (GET /v1/sessions/{session_id}) und lies metadata. Das beanspruchte Arbeitselement enthält die Sitzungs-ID, aber nicht die Metadaten.
  3. Stelle die Dateien im Arbeitsverzeichnis bereit, bevor ein Tool ausgeführt wird.

Das cURL-Beispiel liest ein Zugriffstoken aus ANTHROPIC_AUTH_TOKEN. Um eines zu erhalten, richte Workload Identity Federation mit dem Standard-Scope workspace:developer ein, wie es Föderation einrichten beschreibt. Tausche dann das Identitätstoken deines Workloads gegen ein Zugriffstoken, wie es Von deinem Workload aus authentifizieren zeigt. Setze ANTHROPIC_AUTH_TOKEN nur in der Shell, in der du das cURL-Beispiel ausführst, da die Variable Vorrang vor deinen Föderationseinstellungen hat. Authentifizierung listet die anderen Anmeldedaten auf, die die API akzeptiert, etwa den API-Key aus dem Schnellstart.

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

Nächste Schritte

Lies die Queue-Tiefe aus, stoppe Sitzungen und Worker sauber und behebe häufige Fehler.

War diese Seite hilfreich?