---
title: Selbst gehostete Worker bereitstellen
url: https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-workers
description: "Wähle, wie selbst gehostete Sandbox-Worker Arbeit beanspruchen und wo Sitzungen laufen: dauerhaft aktiv oder per Webhook ausgelöst, in einem Prozess oder mit einer Sandbox pro Sitzung."
featureMetadata:
topic:
title: Managed Agents
url: https://platform.claude.com/docs/en/managed-agents/overview
status: beta
betaHeader: managed-agents-2026-04-01
---
Der [Schnellstart](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes#quickstart) führt einen `ant`-CLI-Worker aus, der kontinuierlich pollt und jede Sitzung in einem Prozess ausführt. Diese Seite behandelt die anderen Möglichkeiten, einen Worker auszuführen, und wie du zwischen ihnen wählst.
## Ein Bereitstellungsmuster wählen
Beim Bereitstellen von Workern musst du zwei Entscheidungen treffen: wie der Worker Arbeit beansprucht und wo jede Sitzung läuft.
**Wie der Worker Arbeit beansprucht:**
* **Dauerhaft aktiv:** Ein langlebiger Prozess pollt die Warteschlange kontinuierlich und benötigt nur ausgehendes HTTPS. Dies ist die einfachste Einrichtung.
* **Per Webhook ausgelöst:** Ein Handler wird bei `session.status_run_started` aktiviert und beginnt mit dem Polling. Dadurch wird ein untätiger Poller vermieden, es ist jedoch ein [Webhook](https://platform.claude.com/docs/de/managed-agents/webhooks)-Endpunkt erforderlich, den Anthropic erreichen kann.
**Wo jede Sitzung läuft:**
* **Im Prozess:** Der Worker, der eine Sitzung beansprucht, führt auch deren Tool-Aufrufe aus, in einem gemeinsamen Arbeitsverzeichnis.
* **Sandbox pro Sitzung:** Ein Poller startet für jede beanspruchte Sitzung eine neue Sandbox. Wähle dies für stärkere Isolation: ein frisches Dateisystem, Ressourcenlimits oder Netzwerkkontrollen pro Sitzung.
Die CLI- und SDK-Worker unterstützen unterschiedliche Kombinationen:
| Fähigkeit | `ant` CLI | SDK (Python, TypeScript, Go) |
| ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ----------------------------------------- |
| Dauerhaft aktives Polling | Ja | Ja |
| Per Webhook ausgelöst | Nein | Ja |
| Sandbox pro Sitzung | Ja | Ja |
| [Memory Stores](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-memory) | Ja, mit Standard-Synchronisierungseinstellungen | Ja, mit konfigurierbarer Synchronisierung |
| [Benutzerdefinierte Tools](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-custom-tools) | Nein | Ja |
Siehe [Referenz für selbst gehostete Worker](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-reference) für jedes CLI-Flag und jede SDK-Option. Für mehr Kontrolle rufe die [Environments-Work-Endpunkte](https://platform.claude.com/docs/de/api/beta/environments/work) direkt auf und implementiere deinen eigenen Worker.
## Einen dauerhaft aktiven Worker ausführen
Starte einen Worker, der die Warteschlange kontinuierlich pollt. Er authentifiziert sich mit dem [Umgebungsschlüssel](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes#run-your-first-session) aus dem Schnellstart:
```bash CLI
ant beta:worker poll --workdir /workspace
```
```python Python
import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker
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:
worker = EnvironmentWorker(
client,
environment_id=environment_id,
environment_key=environment_key,
workdir="/workspace",
)
task = asyncio.create_task(worker.run())
# Das Abbrechen des Tasks statt des Beendens des Prozesses erlaubt dem Worker, sein
# laufendes Work-Item zu stoppen und geänderte Memory-Dateien vor dem Beenden hochzuladen.
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 environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
const client = new Anthropic({ authToken: environmentKey });
const controller = new AbortController();
// Ein Abbruch bei einem der beiden Signale lässt den Worker geänderte Memory-Dateien hochladen und seine
// Store-Verzeichnisse entfernen, bevor der Prozess beendet wird.
process.once("SIGINT", () => controller.abort());
process.once("SIGTERM", () => controller.abort());
await new EnvironmentWorker({
client,
environmentId,
environmentKey,
workdir: "/workspace",
signal: controller.signal
}).run();
```
Das C#-SDK hat keinen `EnvironmentWorker`. Führe stattdessen den `ant`-CLI-Worker aus: `ant beta:worker poll --workdir /workspace`.
```go Go
package main
import (
"context"
"log"
"os"
"os/signal"
"syscall"
"github.com/anthropics/anthropic-sdk-go"
"github.com/anthropics/anthropic-sdk-go/lib/environments"
"github.com/anthropics/anthropic-sdk-go/option"
)
func main() {
environmentKey := os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")
environmentID := os.Getenv("ANTHROPIC_ENVIRONMENT_ID")
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
client := anthropic.NewClient(option.WithAuthToken(environmentKey))
worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
EnvironmentID: environmentID,
EnvironmentKey: environmentKey,
Workdir: "/workspace",
})
if err := worker.Run(ctx); err != nil {
log.Fatalf("worker: %v", err)
}
}
```
Das Java-SDK hat keinen `EnvironmentWorker`. Führe stattdessen den `ant`-CLI-Worker aus: `ant beta:worker poll --workdir /workspace`.
Das PHP-SDK hat keinen `EnvironmentWorker`. Führe stattdessen den `ant`-CLI-Worker aus: `ant beta:worker poll --workdir /workspace`.
Das Ruby-SDK hat keinen `EnvironmentWorker`. Führe stattdessen den `ant`-CLI-Worker aus: `ant beta:worker poll --workdir /workspace`.
## Worker über Webhooks auslösen
Definiere in der [Console](https://platform.claude.com/settings/workspaces/default/webhooks) einen Webhook-Endpunkt, der auf `session.status_run_started`-Events lauscht. Details findest du unter [Webhooks](https://platform.claude.com/docs/de/managed-agents/webhooks).
Exportiere zusammen mit der Umgebungs-ID und dem Schlüssel aus dem [Schnellstart](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes#run-your-first-session) den Webhook-Signaturschlüssel auf deinem Handler-Host. Der Handler verwendet ihn, um eingehende Payloads zu verifizieren.
```bash
export ANTHROPIC_WEBHOOK_SIGNING_KEY="whsec_..."
```
Rufe den Worker auf, wenn `session.status_run_started` ausgelöst wird. Der Handler leert die Warteschlange und übergibt jedes beanspruchte Arbeitselement an `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`), das Skills herunterlädt, Tool-Aufrufe ausführt, Ergebnisse zurücksendet und zurückkehrt.
Um Webhook-Signaturen zu verifizieren, installiere das Webhooks-Extra: `pip install "anthropic[webhooks]"`.
```python Python
import asyncio
import os
import anthropic
import standardwebhooks # installed by the anthropic[webhooks] extra
environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
client = anthropic.AsyncAnthropic(
auth_token=environment_key,
)
# Wird von shutdown() abgebrochen, damit ein laufendes Work-Item geänderte Memory-Dateien hochladen und
# seine Store-Verzeichnisse entfernen kann, bevor der Prozess endet.
inflight: set[asyncio.Task[None]] = set()
# Awaite dies im Shutdown-Hook des Hosts, z. B. einem ASGI-Lifespan-Shutdown (der Code nach
# `yield` in einem FastAPI-Lifespan), den uvicorn bei SIGTERM ausführt. uvicorn lässt offene Requests
# vor diesem Hook abschließen; setze daher --timeout-graceful-shutdown, um die Wartezeit zu begrenzen.
async def shutdown() -> None:
for task in inflight:
task.cancel()
await asyncio.gather(*inflight, return_exceptions=True)
async def handle(raw: bytes, headers: dict[str, str]) -> tuple[dict[str, str], int]:
try:
event = client.beta.webhooks.unwrap(raw.decode(), headers=headers)
except standardwebhooks.WebhookVerificationError:
return {"error": "signature verification failed"}, 401
if event.data.type != "session.status_run_started":
return {"status": "ignored"}, 200
task = asyncio.create_task(run_queued_work())
inflight.add(task)
task.add_done_callback(inflight.discard)
try:
# Geschützt (shielded): Eine verworfene oder abgelaufene Zustellung darf das Item nicht abbrechen; shutdown() tut es.
await asyncio.shield(task)
except asyncio.CancelledError:
return {"status": "shutting down"}, 503
return {"status": "ok"}, 200
async def run_queued_work() -> None:
async for work in client.beta.environments.work.poller(
environment_id=environment_id,
environment_key=environment_key,
block_ms=None,
reclaim_older_than_ms=2000,
drain=True,
auto_stop=False,
):
await client.beta.environments.work.worker(workdir="/workspace").handle_item(
work_id=work.id,
environment_id=environment_id,
session_id=work.data.id,
environment_key=environment_key,
# Das sitzungsspezifische Secret ermöglicht dem Worker, die Memory-Stores der Sitzung zu mounten.
work_secret=work.secret,
)
```
```typescript TypeScript
import Anthropic from "@anthropic-ai/sdk";
const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
const client = new Anthropic({
authToken: environmentKey
});
// Rufe shutdown.abort() aus dem SIGTERM/SIGINT-Handler des Hosts auf, zusammen mit dem Schließen des Servers,
// und warte dann vor dem Beenden auf laufende handle()-Aufrufe: Der Abort lässt ein laufendes Work-Item
// zuerst geänderte Memory-Dateien hochladen und seine Store-Verzeichnisse entfernen.
export const shutdown = new AbortController();
export async function handle(req: Request): Promise {
// Bestätige nie eine Zustellung, deren Arbeit hier nicht läuft; ein 503 lässt den Absender erneut versuchen.
if (shutdown.signal.aborted) {
return Response.json({ status: "shutting down" }, { status: 503 });
}
const body = await req.text();
let event;
try {
event = client.beta.webhooks.unwrap(body, { headers: Object.fromEntries(req.headers) });
} catch {
return new Response("signature verification failed", { status: 401 });
}
if (event.data.type !== "session.status_run_started") {
return Response.json({ status: "ignored" });
}
for await (const work of client.beta.environments.work.poller({
environmentId,
environmentKey,
blockMs: null,
reclaimOlderThanMs: 2000,
drain: true,
autoStop: false,
signal: shutdown.signal
})) {
await client.beta.environments.work.worker({ workdir: "/workspace" }).handleItem({
workId: work.id,
environmentId,
sessionId: work.data.id,
environmentKey,
// Das Secret pro Session ermöglicht es dem Worker, die Memory-Stores der Session einzubinden.
workSecret: work.secret ?? undefined,
signal: shutdown.signal
});
}
// Poller und handleItem kehren bei Abort still zurück, sodass ein abgebrochener Drain hier landet.
if (shutdown.signal.aborted) {
return Response.json({ status: "shutting down" }, { status: 503 });
}
return Response.json({ status: "ok" });
}
```
Das C#-SDK hat keinen `EnvironmentWorker`. Um Arbeitselemente aus deinem eigenen Code zu verarbeiten, rufe die [Environments-Work-Endpunkte](https://platform.claude.com/docs/de/api/beta/environments/work) auf.
```go Go
package main
import (
"context"
"encoding/json"
"errors"
"io"
"log/slog"
"net/http"
"os"
"os/signal"
"syscall"
"github.com/anthropics/anthropic-sdk-go"
"github.com/anthropics/anthropic-sdk-go/lib/environments"
"github.com/anthropics/anthropic-sdk-go/option"
"github.com/anthropics/anthropic-sdk-go/packages/param"
)
var (
environmentKey = os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")
environmentID = os.Getenv("ANTHROPIC_ENVIRONMENT_ID")
client = anthropic.NewClient(
option.WithAuthToken(environmentKey),
option.WithWebhookKey(os.Getenv("ANTHROPIC_WEBHOOK_SIGNING_KEY")),
)
worker = environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
Workdir: "/workspace",
})
// Wird bei SIGINT oder SIGTERM abgebrochen (in main gesetzt), damit ein laufendes Work-Item
// geänderte Memory-Dateien hochladen und seine Store-Verzeichnisse vor dem Beenden entfernen kann.
shutdown context.Context
)
func handle(w http.ResponseWriter, r *http.Request) {
body, err := io.ReadAll(r.Body)
if err != nil {
http.Error(w, "bad request", http.StatusBadRequest)
return
}
event, err := client.Beta.Webhooks.Unwrap(body, r.Header)
if err != nil {
http.Error(w, "signature verification failed", http.StatusUnauthorized)
return
}
if event.Data.Type != "session.status_run_started" {
json.NewEncoder(w).Encode(map[string]string{"status": "ignored"})
return
}
// Das Go SDK bietet keine RunOne-Komfortfunktion: Leere ausstehende Items
// mit WorkPoller und führe jedes einzelne mit HandleItem aus.
// Von r.Context() entkoppeln: Die Session kann das Webhook-Zustellungs-Timeout überdauern.
// Der prozessweite Shutdown-Kontext beendet das Item bei SIGTERM dennoch sauber.
ctx := shutdown
poller := environments.NewWorkPoller(ctx, client, environments.WorkPollerOptions{
EnvironmentID: environmentID,
EnvironmentKey: environmentKey,
BlockMs: param.Null[int64](),
ReclaimOlderThanMs: param.NewOpt[int64](2000),
Drain: true,
AutoStop: param.NewOpt(false),
})
defer poller.Close()
for poller.Next() {
item := poller.Current()
if err := worker.HandleItem(ctx, environments.HandleItemOptions{
WorkID: item.ID,
EnvironmentID: item.EnvironmentID,
SessionID: item.Data.ID,
EnvironmentKey: environmentKey,
// Das Secret pro Session ermöglicht es dem Worker, die Memory-Stores der Session einzubinden.
WorkSecret: item.Secret,
}); err != nil {
slog.Error("handle work item", "work_id", item.ID, "err", err)
http.Error(w, "internal error", http.StatusInternalServerError)
return
}
}
if err := poller.Err(); err != nil {
slog.Error("poll work queue", "err", err)
http.Error(w, "internal error", http.StatusInternalServerError)
return
}
json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
}
func main() {
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
shutdown = ctx
server := &http.Server{Addr: ":8080"}
http.HandleFunc("POST /webhook", handle)
go func() {
if err := server.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
slog.Error("http server", "err", err)
os.Exit(1)
}
}()
// Bei einem Signal keine Zustellungen mehr annehmen und erst zurückkehren, nachdem laufende
// Handler, und damit der Memory-Teardown ihrer Work-Items, abgeschlossen sind.
<-ctx.Done()
if err := server.Shutdown(context.Background()); err != nil {
slog.Error("http shutdown", "err", err)
}
}
```
Das Java-SDK hat keinen `EnvironmentWorker`. Um Arbeitselemente aus deinem eigenen Code zu verarbeiten, rufe die [Environments-Work-Endpunkte](https://platform.claude.com/docs/de/api/beta/environments/work) auf.
Das PHP-SDK hat keinen `EnvironmentWorker`. Um Arbeitselemente aus deinem eigenen Code zu verarbeiten, rufe die [Environments-Work-Endpunkte](https://platform.claude.com/docs/de/api/beta/environments/work) auf.
Das Ruby-SDK hat keinen `EnvironmentWorker`. Um Arbeitselemente aus deinem eigenen Code zu verarbeiten, rufe die [Environments-Work-Endpunkte](https://platform.claude.com/docs/de/api/beta/environments/work) auf.
Da der Handler die Arbeit selbst beansprucht, muss er [das Secret des Arbeitselements weiterleiten](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-workers#forward-the-work-items-secret), wie es hier das Argument `work_secret` (typescript: `workSecret`; go: `WorkSecret`) tut.
Dieser Handler führt jedes beanspruchte Arbeitselement in einem Prozess auf einem Host aus. Wenn deine Sitzungen denselben Memory Store anhängen, siehe [Sitzungen isolieren, die sich einen Store teilen](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-memory#isolate-sessions-that-share-a-store).
## Eine Sandbox pro Sitzung ausführen
Ein Poller auf dem Host beansprucht Arbeit und ruft dein Skript einmal pro Arbeitselement auf. Das Skript startet eine Sandbox für genau diese eine Sitzung.
Installiere `ant` und lege `ant beta:worker run` als Entrypoint fest. Wenn eine Sandbox startet, liest sie die Sitzungsdetails aus Umgebungsvariablen, bearbeitet diese Sitzung und beendet sich. Das Basis-Image muss `/bin/bash` bereitstellen; `curl` wird nur zur Build-Zeit verwendet.
```dockerfile
FROM your-base-image
ARG ANT_VERSION=1.42.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"]
```
Das Skript leitet die Sitzungsdetails in eine neue Sandbox weiter. Es benötigt `jq` auf dem Poller-Host.
```bash
#!/bin/bash
# spawn.sh: wird einmal pro beanspruchtem 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 die `ANTHROPIC_*`-Variablen, die das Skript weiterleitet, mit Ausnahme des Secrets. Siehe [Umgebungsvariablen](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-reference#environment-variables).
`/host/outputs` ist ein Host-Verzeichnis deiner Wahl. Wenn du es unter `/workspace` einbindest, kannst du die Ergebnisse der Sitzung abrufen, nachdem die Sandbox beendet wurde. Der Mount erfasst außerdem den heruntergeladenen `skills/`-Baum und alle Zwischendateien.
```bash
ant beta:worker poll --on-work ./spawn.sh
```
### Das Secret des Arbeitselements weiterleiten
Jedes beanspruchte Arbeitselement kann ein sitzungsspezifisches `secret` (csharp, go: `Secret`) enthalten, das Anthropic 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 Prozess beansprucht und ausführt (`ant beta:worker poll` ohne `--on-work` oder `EnvironmentWorker` mit `run()` (go: `Run()`)), gibt das Secret selbst weiter. Wenn dein eigener Code zwischen dem Beanspruchen und dem Worker steht, leitest du es weiter:
| Du beanspruchst Arbeit mit | Das Secret kommt an als | Übergib es an den Worker als |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ant beta:worker poll --on-work` | Das Feld `secret` im JSON des Arbeitselements auf der Standardeingabe deines Skripts | `ANTHROPIC_WORK_SECRET` in der Umgebung der Sandbox |
| `work.poller()` (go: `environments.NewWorkPoller()`) des 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()`) |
Übergib das Secret nur an die Sandbox, 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 sich zum Umgebungsschlüssel verhält.
### Sandboxes aus dem SDK-Poller starten
Um Arbeit aus deinem eigenen Code statt mit `ant beta:worker poll --on-work` zu beanspruchen, verwende `work.poller()` (go: `environments.NewWorkPoller()`). Es pollt die Warteschlange und gibt dir jede beanspruchte Sitzung, und du startest die Sandbox:
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 [Eine Sandbox pro Sitzung ausführen](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-workers#run-one-sandbox-per-session) gezeigt.
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, wie in [Eine Sandbox pro Sitzung ausführen](https://platform.claude.com/docs/de/managed-agents/self-hosted-sandboxes-workers#run-one-sandbox-per-session) gezeigt.
```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 Environment-
# Key (niemals deinen API-Key) und das sitzungsspezifische Secret des Work Items 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 {
console.log(`claimed session ${work.data.id}`);
// Ersetze `docker run` durch deinen eigenen Sandbox-Launcher. Leite den Environment-
// Key (niemals deinen API-Key) und das sitzungsspezifische Secret des Work Items 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);
}
```
Das C#-SDK hat keinen Helfer, der nach Arbeit pollt. Um Arbeit aus deinem eigenen Code zu beanspruchen, rufe die [Environments-Work-Endpunkte](https://platform.claude.com/docs/de/api/beta/environments/work) auf.
```go Go
package main
import (
"context"
"fmt"
"log"
"os"
"os/exec"
"github.com/anthropics/anthropic-sdk-go"
"github.com/anthropics/anthropic-sdk-go/lib/environments"
"github.com/anthropics/anthropic-sdk-go/option"
"github.com/anthropics/anthropic-sdk-go/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 Environment-
// Key (niemals deinen API-Key) und das sitzungsspezifische Secret des Work Items 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)
}
}
}
```
Das Java-SDK hat keinen Helfer, der nach Arbeit pollt. Um Arbeit aus deinem eigenen Code zu beanspruchen, rufe die [Environments-Work-Endpunkte](https://platform.claude.com/docs/de/api/beta/environments/work) auf.
Das PHP-SDK hat keinen Helfer, der nach Arbeit pollt. Um Arbeit aus deinem eigenen Code zu beanspruchen, rufe die [Environments-Work-Endpunkte](https://platform.claude.com/docs/de/api/beta/environments/work) auf.
Das Ruby-SDK hat keinen Helfer, der nach Arbeit pollt. Um Arbeit aus deinem eigenen Code zu beanspruchen, rufe die [Environments-Work-Endpunkte](https://platform.claude.com/docs/de/api/beta/environments/work) auf.
### 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.
```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 weitergereicht hat, einschließlich ANTHROPIC_WORK_SECRET.
task = asyncio.create_task(worker.handle_item())
# Das Abbrechen des Tasks beim Stoppen des Containers ermöglicht dem Worker, geänderte
# Memory-Dateien hochzuladen und die Store-Verzeichnisse vor dem Beenden zu 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();
// Ein 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();
```
Das C#-SDK hat keinen `EnvironmentWorker`.
```go Go
package main
import (
"context"
"log"
"os"
"os/signal"
"syscall"
"github.com/anthropics/anthropic-sdk-go"
"github.com/anthropics/anthropic-sdk-go/lib/environments"
"github.com/anthropics/anthropic-sdk-go/option"
)
func main() {
// Das Abbrechen des Kontexts beim Stoppen des Containers lässt den 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)
}
}
```
Das Java-SDK hat keinen `EnvironmentWorker`.
Das PHP-SDK hat keinen `EnvironmentWorker`.
Das Ruby-SDK hat keinen `EnvironmentWorker`.
## Dateien für eine Sitzung bereitstellen
Anthropic bindet keine Dateien oder GitHub-Repositories in selbst gehostete Sandboxes ein. So machst du sitzungsspezifische Dateien verfügbar:
1. Übergib Dateiverweise, 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. Lege die Dateien im Arbeitsverzeichnis ab, bevor die Tool-Ausführung beginnt.
```bash cURL
curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d '{
"agent": "'"$AGENT_ID"'",
"environment_id": "'"$ANTHROPIC_ENVIRONMENT_ID"'",
"metadata": {"input_file": "s3://my-bucket/data.csv"}
}'
```
```bash CLI
ant beta:sessions create \
--agent "$AGENT_ID" \
--environment-id "$ANTHROPIC_ENVIRONMENT_ID" \
--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 { ["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"}
)
```
## Nächste Schritte
Lies die Warteschlangentiefe aus, stoppe Sitzungen und Worker sauber und behebe häufige Fehler.
Modell der geteilten Verantwortung für selbst gehostete Sandbox-Umgebungen.