---
title: Eine Sandbox pro Sitzung ausführen
url: https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-per-session
description: Gib jeder Sitzung ihre eigene selbst gehostete Sandbox mit dem Helm-Chart auf Kubernetes, einem Spawn-Skript oder dem SDK-Poller.
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
  zdr:
    eligibility: not-eligible
    note: Nicht für ZDR berechtigt, außer bei selbst gehosteten Managed Agents. Sitzungen sind zustandsbehaftete Ressourcen; Transkripte bleiben erhalten, bis du sie löschst.
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: beta
    Claude Platform on AWS: beta
---

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](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-workers#choose-a-deployment-pattern).

Du kannst es auf drei Arten einrichten:

* **[Helm-Chart auf Kubernetes](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-per-session#run-sandboxes-on-kubernetes):** Der Dispatcher von Anthropic beansprucht Arbeit und startet für jede Sitzung einen Pod auf deinem Cluster.
* **[Spawn-Skript](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-with-a-spawn-script):** Die `ant` CLI beansprucht Arbeit und ruft dein Skript auf, das auf einer beliebigen Plattform eine Sandbox startet.
* **[SDK-Poller](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-from-the-sdk-poller):** Dein eigener Code beansprucht Arbeit und startet die Sandbox.

Die Abschnitte nach [Sandboxes auf Kubernetes ausführen](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-per-session#run-sandboxes-on-kubernetes) 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](https://gvisor.dev/) 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](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-memory) mit den Standard-Synchronisierungseinstellungen und unterstützen keine [benutzerdefinierten Tools](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-custom-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](https://github.com/kubernetes-sigs/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](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes#run-your-first-session) sowie das TLS-Zertifikat des Dispatchers.

Die [Installationsanleitung auf GitHub](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md) 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:

<File filename="cma-values.yaml">
  ```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
  ```
</File>

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:

```bash
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.

<Warning>
  Entferne das Chart nicht allein mit `helm uninstall`. Dieser Befehl löscht die Netzwerkrichtlinien und lässt die Sandboxes der Sitzungen ohne sie weiterlaufen. Stoppe zuerst den Dispatcher und lösche die Sandboxes, in der Reihenfolge, die der [Abschnitt „Removal“ der Installationsanleitung](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#removal) vorgibt.
</Warning>

### 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](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#install) 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](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#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](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#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.

<Steps>
  <Step title="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.

    <File filename="Dockerfile">
      ```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"]
      ```
    </File>
  </Step>

  <Step title="Das Spawn-Skript schreiben">
    Das Skript leitet die Sitzungsdetails in eine neue Sandbox weiter. Es benötigt `jq` auf dem Poller-Host.

    <File filename="spawn.sh">
      ```bash
      #!/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
      ```
    </File>

    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](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-reference#environment-variables).

    `/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.
  </Step>

  <Step title="Den Poller starten">
    ```bash
    ant beta:worker poll --on-work ./spawn.sh
    ```
  </Step>
</Steps>

## Das Secret des Arbeitselements weiterleiten

Jedes beanspruchte Arbeitselement kann ein `secret` (csharp, go: `Secret`) enthalten, das Anthropic für diese Sitzung ausstellt. Der Worker, der die Sitzung ausführt, benötigt es, um [Memory Stores](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-memory) einzubinden.

Ein Worker, der Sitzungen in einem einzigen Prozess beansprucht und ausführt, gibt das Secret selbst weiter. `EnvironmentWorker` mit `run()` (go: `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 mit                                                                                                | Das Secret kommt an als                                                          | Gib es an den Worker weiter als                                                                                                                                                                       |
| ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ant beta:worker poll --on-work`                                                                                          | Das Feld `secret` des Arbeitselement-JSON auf der Standardeingabe deines Skripts | `ANTHROPIC_WORK_SECRET` in der Umgebung der Sandbox                                                                                                                                                   |
| `work.poller()` (typescript: `new WorkPoller()`; go: `environments.NewWorkPoller()`) des Python-, TypeScript- oder Go-SDK | Das Feld `secret` (go: `Secret`) jedes beanspruchten Arbeitselements             | `ANTHROPIC_WORK_SECRET` in der Umgebung der Sandbox oder das Argument `work_secret` (typescript: `workSecret`; go: `WorkSecret`) für `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) |

Gib das Secret nur an die Sandbox weiter, die diese Sitzung bedient, und protokolliere es niemals. Unter [Sicherheitsmodell](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-security) 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()` (typescript: `new WorkPoller()`; go: `environments.NewWorkPoller()`). Er fragt die Queue ab und übergibt dir jede beanspruchte Sitzung, und du startest die Sandbox:

<CodeGroup exclude="shell, csharp, java, php, ruby">
  <CodeGroupItem language="cURL">
    Arbeit in einer Schleife zu beanspruchen und für jede Sitzung eine Sandbox zu starten, erfordert mehr Logik als ein einzelner Shell-Befehl. Führe in der Shell `ant beta:worker poll --on-work` mit einem Spawn-Skript aus, wie in [Sandboxes mit einem Spawn-Skript starten](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-with-a-spawn-script).
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    Um Arbeit aus der Shell zu beanspruchen und für jede Sitzung eine Sandbox zu starten, führe `ant beta:worker poll --on-work` mit einem Spawn-Skript aus. Siehe [Sandboxes mit einem Spawn-Skript starten](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-with-a-spawn-script).
  </CodeGroupItem>

  ```python Python
  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())
  ```

  ```typescript TypeScript
  import { spawn } from "node:child_process";
  import { once } from "node:events";
  import Anthropic from "@anthropic-ai/sdk";
  import { WorkPoller } from "@anthropic-ai/sdk/helpers/beta/environments";
  import type { BetaSelfHostedWork } from "@anthropic-ai/sdk/resources/beta/environments";

  const 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
  ];

  const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
  const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
  const client = new Anthropic({ authToken: environmentKey });

  async function launchContainer(work: BetaSelfHostedWork): Promise<void> {
    console.log(`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.
    const env = {
      ...process.env,
      ANTHROPIC_WORK_ID: work.id,
      ANTHROPIC_SESSION_ID: work.data.id,
      ANTHROPIC_WORK_SECRET: work.secret ?? ""
    };
    const forward = SANDBOX_ENV.flatMap((name) => ["-e", name]);
    const launcher = spawn("docker", ["run", "--rm", "--detach", ...forward, "your-image"], {
      env,
      stdio: "inherit"
    });
    await once(launcher, "close");
  }

  const poller = new WorkPoller({
    client,
    environmentId,
    environmentKey,
    autoStop: false // the launched sandbox owns the stop call
  });

  for await (const work of poller) {
    await launchContainer(work);
  }
  ```

  <CodeGroupItem language="C#">
    Das C#-SDK hat keinen Helfer, der nach Arbeit fragt. Um Arbeit aus deinem eigenen Code zu beanspruchen, rufe die [Environments-Work-Endpunkte](https://platform.claude.com/docs/de/api/beta/environments/work) auf, um ein Element abzufragen und es zu bestätigen.
  </CodeGroupItem>

  ```go Go
  package main

  import (
  	"context"
  	"fmt"
  	"log"
  	"os"
  	"os/exec"

  	"github.com/anthropics/anthropic-sdk-go/v2"
  	"github.com/anthropics/anthropic-sdk-go/v2/lib/environments"
  	"github.com/anthropics/anthropic-sdk-go/v2/option"
  	"github.com/anthropics/anthropic-sdk-go/v2/packages/param"
  )

  var sandboxEnv = []string{
  	"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
  }

  func launchContainer(ctx context.Context, work *anthropic.BetaSelfHostedWork) error {
  	fmt.Printf("claimed session %s\n", 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.
  	args := []string{"run", "--rm", "--detach"}
  	for _, name := range sandboxEnv {
  		args = append(args, "-e", name)
  	}
  	launcher := exec.CommandContext(ctx, "docker", append(args, "your-image")...)
  	launcher.Env = append(os.Environ(),
  		"ANTHROPIC_WORK_ID="+work.ID,
  		"ANTHROPIC_SESSION_ID="+work.Data.ID,
  		"ANTHROPIC_WORK_SECRET="+work.Secret,
  	)
  	launcher.Stdout, launcher.Stderr = os.Stdout, os.Stderr
  	return launcher.Run()
  }

  func main() {
  	environmentID := os.Getenv("ANTHROPIC_ENVIRONMENT_ID")
  	environmentKey := os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")

  	client := anthropic.NewClient(option.WithAuthToken(environmentKey))

  	ctx := context.Background()

  	poller := environments.NewWorkPoller(ctx, client, environments.WorkPollerOptions{
  		EnvironmentID:  environmentID,
  		EnvironmentKey: environmentKey,
  		AutoStop:       param.NewOpt(false), // the launched sandbox owns the stop call
  	})
  	defer poller.Close()

  	for work, err := range poller.All() {
  		if err != nil {
  			log.Fatal(err)
  		}
  		if err := launchContainer(ctx, work); err != nil {
  			log.Fatal(err)
  		}
  	}
  }
  ```

  <CodeGroupItem language="Java">
    Das Java-SDK hat keinen Helfer, der nach Arbeit fragt. Um Arbeit aus deinem eigenen Code zu beanspruchen, rufe die [Environments-Work-Endpunkte](https://platform.claude.com/docs/de/api/beta/environments/work) auf, um ein Element abzufragen und es zu bestätigen.
  </CodeGroupItem>

  <CodeGroupItem language="PHP">
    Das PHP-SDK hat keinen Helfer, der nach Arbeit fragt. Um Arbeit aus deinem eigenen Code zu beanspruchen, rufe die [Environments-Work-Endpunkte](https://platform.claude.com/docs/de/api/beta/environments/work) auf, um ein Element abzufragen und es zu bestätigen.
  </CodeGroupItem>

  <CodeGroupItem language="Ruby">
    Das Ruby-SDK hat keinen Helfer, der nach Arbeit fragt. Um Arbeit aus deinem eigenen Code zu beanspruchen, rufe die [Environments-Work-Endpunkte](https://platform.claude.com/docs/de/api/beta/environments/work) auf, um ein Element abzufragen und es zu bestätigen.
  </CodeGroupItem>
</CodeGroup>

## 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](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-custom-tools) oder [nicht standardmäßige Memory-Synchronisierungseinstellungen](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-memory#configure-sync) verwenden muss. Der Entrypoint erstellt `EnvironmentWorker` und ruft `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) auf, das dieselben `ANTHROPIC_*`-Variablen liest, die das Spawn-Skript weiterleitet.

<CodeGroup exclude="shell, csharp, java, php, ruby">
  <CodeGroupItem language="cURL">
    Ein Worker ist ein langlebiger Prozess, keine einzelne HTTP-Anfrage. Um benutzerdefinierte Tools bereitzustellen oder die Memory-Synchronisierungseinstellungen zu ändern, verwende `EnvironmentWorker` im Python-, TypeScript- oder Go-SDK.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    Der `ant`-CLI-Worker (`ant beta:worker run`) kann keine benutzerdefinierten Tools bereitstellen und die Memory-Synchronisierungseinstellungen nicht ändern. Um eines davon zu tun, verwende `EnvironmentWorker` im Python-, TypeScript- oder Go-SDK.
  </CodeGroupItem>

  ```python Python
  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())
  ```

  ```typescript TypeScript
  import Anthropic from "@anthropic-ai/sdk";
  import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments";

  const client = new Anthropic({ authToken: process.env.ANTHROPIC_ENVIRONMENT_KEY });
  const controller = new AbortController();
  // Der Abbruch beim Stoppen des Containers lässt den Worker geänderte Memory-
  // Dateien hochladen und die Store-Verzeichnisse entfernen, bevor er beendet wird.
  process.once("SIGTERM", () => controller.abort());
  process.once("SIGINT", () => controller.abort());

  // Ohne Argumente liest handleItem() die ANTHROPIC_*-Variablen, die das Spawn-
  // Skript weitergeleitet hat, einschließlich ANTHROPIC_WORK_SECRET.
  await new EnvironmentWorker({
    client,
    workdir: "/workspace",
    signal: controller.signal
  }).handleItem();
  ```

  <CodeGroupItem language="C#">
    Das C#-SDK hat keinen `EnvironmentWorker`.
  </CodeGroupItem>

  ```go Go
  package main

  import (
  	"context"
  	"log"
  	"os"
  	"os/signal"
  	"syscall"

  	"github.com/anthropics/anthropic-sdk-go/v2"
  	"github.com/anthropics/anthropic-sdk-go/v2/lib/environments"
  	"github.com/anthropics/anthropic-sdk-go/v2/option"
  )

  func main() {
  	// Wird der Kontext beim Stoppen des Containers abgebrochen, kann der Worker
  	// geänderte Memory-Dateien hochladen und die Store-Verzeichnisse entfernen, bevor er beendet wird.
  	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
  	defer stop()

  	client := anthropic.NewClient(option.WithAuthToken(os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")))
  	worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
  		Workdir: "/workspace",
  	})
  	// Mit Nullwert-Optionen liest HandleItem die ANTHROPIC_*-Variablen, die das Spawn-
  	// Skript weitergeleitet hat, einschließlich ANTHROPIC_WORK_SECRET.
  	if err := worker.HandleItem(ctx, environments.HandleItemOptions{}); err != nil {
  		log.Fatalf("worker: %v", err)
  	}
  }
  ```

  <CodeGroupItem language="Java">
    Das Java-SDK hat keinen `EnvironmentWorker`.
  </CodeGroupItem>

  <CodeGroupItem language="PHP">
    Das PHP-SDK hat keinen `EnvironmentWorker`.
  </CodeGroupItem>

  <CodeGroupItem language="Ruby">
    Das Ruby-SDK hat keinen `EnvironmentWorker`.
  </CodeGroupItem>
</CodeGroup>

## 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` (csharp, go: `Metadata`) der Sitzung.
2. Rufe in deinem Spawn-Skript oder `--on-work`-Handler die Sitzung ab (`GET /v1/sessions/{session_id}`) und lies `metadata` (csharp, go: `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](https://platform.claude.com/docs/de/manage-claude/workload-identity-federation#set-up-federation) beschreibt. Tausche dann das Identitätstoken deines Workloads gegen ein Zugriffstoken, wie es [Von deinem Workload aus authentifizieren](https://platform.claude.com/docs/de/manage-claude/workload-identity-federation#authenticate-from-your-workload) 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](https://platform.claude.com/docs/de/manage-claude/authentication) listet die anderen Anmeldedaten auf, die die API akzeptiert, etwa den API-Key aus dem Schnellstart.

<CodeGroup>
  ```bash cURL
  curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
    -H "authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "agent": "agent_011CYm1BLqPXpQRk5khsSXrs",
      "environment_id": "env_01595EKxaaTTGwwY3kyXdtbs",
      "metadata": {"input_file": "s3://my-bucket/data.csv"}
    }'
  ```

  ```bash CLI
  ant beta:sessions create \
    --agent agent_011CYm1BLqPXpQRk5khsSXrs \
    --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
    --metadata '{"input_file": "s3://my-bucket/data.csv"}'
  ```

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

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

  ```csharp C#
  var session = await client.Beta.Sessions.Create(new()
  {
      Agent = agent.ID,
      EnvironmentID = environment.ID,
      Metadata = new Dictionary<string, string> { ["input_file"] = "s3://my-bucket/data.csv" },
  });
  ```

  ```go Go
  session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent:         anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)},
  	EnvironmentID: environment.ID,
  	Metadata: map[string]string{
  		"input_file": "s3://my-bucket/data.csv",
  	},
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var session = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .metadata(SessionCreateParams.Metadata.builder()
          .putAdditionalProperty("input_file", JsonValue.from("s3://my-bucket/data.csv"))
          .build())
      .build());
  ```

  ```php PHP
  $session = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
      metadata: ['input_file' => 's3://my-bucket/data.csv'],
  );
  ```

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

## Nächste Schritte

<CardGroup cols={2}>
  <Card title="Selbst gehostete Worker überwachen und Fehler beheben" icon="lightning" href="https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-operations">
    Lies die Queue-Tiefe aus, stoppe Sitzungen und Worker sauber und behebe häufige Fehler.
  </Card>
</CardGroup>
