Selbst gehostete Sandboxes

Standardmäßig führt Managed Agents Tools und Code in von Anthropic verwalteten Cloud-Sandboxes aus. Selbst gehostete Sandboxes belassen die Orchestrierung auf Anthropics Seite, verlagern die Tool-Ausführung jedoch in Infrastruktur, die du kontrollierst, sodass der Code, das Dateisystem und der ausgehende Netzwerkverkehr des Agents deine Umgebung nie verlassen.

Die Tool-Ausführung bleibt auf deinem Host: Das Dateisystem, das der Agent liest und schreibt, die Prozesse, die er startet, und das Netzwerk, das er erreichen kann, stehen alle unter deiner Kontrolle. Tool-Eingaben und -Ausgaben fließen weiterhin zu Anthropics Control Plane (wo Claude läuft), damit das Modell Ergebnisse sehen und entscheiden kann, was als Nächstes zu tun ist. Siehe das Sicherheitsmodell für die vollständige Datenfluss-Grenze.



Wie es sich von Cloud-Umgebungen unterscheidet

Self-Hosting ist eine gute Wahl, wenn der Agent mit Daten arbeiten muss, die deine Netzwerkgrenze nicht verlassen dürfen, interne Dienste erreichen muss, die nicht öffentlich routbar sind, oder unter den eigenen Compliance- und Audit-Kontrollen deiner Organisation laufen muss.

Für Zero Data Retention und HIPAA-BAA-Berechtigung siehe API und Datenaufbewahrung.



Wann mit MCP-Tunneln kombinieren

Self-Hosting steuert, wo der Code des Agents ausgeführt wird. MCP-Tunnel steuern, wie Anthropic MCP-Server in deinem Netzwerk erreicht. Sie sind unabhängig voneinander: Eine Session, die in Anthropics Cloud-Sandboxes läuft, kann weiterhin private MCP-Server über einen Tunnel erreichen, und eine selbst gehostete Session kann entweder getunnelte oder öffentliche MCP-Server verwenden. Verwende beides, wenn Ausführung und Tool-Zugriff innerhalb deiner Grenze bleiben sollen.



Environment-Worker

Ein Environment-Worker ist ein Prozess, den du auf deiner eigenen Infrastruktur ausführst. Er empfängt Tool-Ausführungsanfragen von Anthropic und führt sie lokal aus. Die self_hosted-Umgebung fungiert als Arbeitswarteschlange: Wenn ihr eine Session zugewiesen wird, stellt Anthropic die Session als Work-Item in die Warteschlange. Dein Worker beansprucht Work-Items aus dieser Warteschlange, startet für jedes einen Ausführungskontext, lädt die Skills des Agents herunter (wiederverwendbare, dateisystembasierte Ressourcen, die dem Agent domänenspezifisches Fachwissen geben), führt die Tool-Aufrufe aus und sendet die Ergebnisse zurück.

Work-Items werden durch Polling der Warteschlange der Umgebung beansprucht: entweder durch einen Always-on-Worker, der kontinuierlich pollt, oder einen Webhook-getriggerten Handler, der bei session.status_run_started aufwacht und mit dem Polling beginnt.

Die CLI und das SDK liefern beide vorgefertigte Worker mit. Die ant-CLI unterstützt nur das Always-on-Muster; das SDK unterstützt sowohl Always-on als auch Webhook-getriggert. Beide sind konfigurierbar: Siehe Selbst gehosteter Worker in der Referenz für CLI-Flags und SDK-Helfer auf dieser Seite für die SDK-Optionen. Für mehr Kontrolle rufe die Environments-Work-Endpunkte direkt auf und implementiere deinen eigenen Worker.



Sandbox-Dateisystem

• /workspace: das systemseitige Standard-Arbeitsverzeichnis für Tool-Ausführung und Skill-Download. Das --workdir-Flag der CLI verwendet standardmäßig das aktuelle Verzeichnis; übergib --workdir /workspace, um dem Systemstandard zu entsprechen. Skills werden nach <workdir>/skills/<name>/ heruntergeladen. Wenn du ein anderes Arbeitsverzeichnis verwendest, aktualisiere den System-Prompt deines Agents, damit Claude die Skill-Dateien finden kann.
• /mnt/session/outputs: Der Worker-Harness weist Claude an, finale Ergebnisse hierhin zu schreiben. Im Sandbox-Modus mountest du ein Host-Verzeichnis an diesem Pfad, um Ausgaben nach dem Ende der Session abzurufen. Im In-Process-Modus schreiben die Datei-Tools des Workers stattdessen unter das Arbeitsverzeichnis, sodass dieser Pfad nicht gilt.



Bevor du beginnst

Du benötigst:

• Einen bestehenden Agent. Wenn du keinen hast, schließe zuerst den Schnellstart ab und notiere dir dessen Agent-ID.
• Einen Linux-Host mit /bin/bash unter genau diesem Pfad. Das Bash-Tool des Workers ruft es direkt auf, ohne PATH zu konsultieren. Das TypeScript-SDK erfordert zusätzlich unzip und tar im PATH sowie Node.js 22 oder neuer; die Python- und Go-SDKs verwenden ihre Standardbibliotheken für die Archiv-Extraktion und haben keine zusätzlichen Binary-Anforderungen.
• Die ant-CLI oder ein Anthropic-SDK (Python, TypeScript oder Go) auf dem Worker-Host.
• Zwei Anmeldedaten: Ein Environment-Key (in den folgenden Schritten in der Console generiert) authentifiziert den Worker gegenüber seiner Warteschlange; dein Claude-API-Key erstellt Sessions und liest Warteschlangen-Statistiken von außerhalb des Worker-Hosts. Die Key-Generierung ist nur über die Console möglich.



Einen Worker ausführen

Wähle Always-on für das einfachste Setup: Ein langlaufender Prozess pollt die Warteschlange kontinuierlich und benötigt nur ausgehendes HTTPS. Wähle Webhook-getriggert, um keinen untätigen Poller laufen zu lassen; dies erfordert einen Webhook-Endpunkt, den Anthropic erreichen kann (siehe Webhooks für Endpunkt-Setup und Signaturverifizierung).



SDK-Helfer

Das SDK bietet drei Helfer auf unterschiedlichen Kontrollebenen. EnvironmentWorker deckt die meisten Anwendungsfälle ab; greife auf die Low-Level-Helfer zurück, wenn du deinen eigenen Prozess pro Session starten oder Tools gegen eine bereits beanspruchte Session ausführen musst.

• EnvironmentWorker: der sofort einsatzbereite Worker. Übernimmt Polling, Setup und Ausführung von Anfang bis Ende.
  • .run(): läuft unbegrenzt und nimmt Sessions auf, sobald sie eintreffen.
  • .handle_item(): bearbeitet ein einzelnes beanspruchtes Work-Item und beendet sich. Übergib die Work-, Session- und Environment-Bezeichner explizit oder lass ihn die ANTHROPIC_*-Variablen lesen, die ant beta:worker poll --on-work für den gestarteten Prozess setzt.
• work.poller(): pollt die Arbeitswarteschlange für dich und gibt dir jede beanspruchte Session. Verwende dies, wenn du entscheiden möchtest, was für jede Session passiert, zum Beispiel das Starten einer Sandbox statt der In-Process-Ausführung von Tools.
  • drain: ob das Polling gestoppt werden soll, sobald die Warteschlange leer ist, statt auf neue Arbeit zu warten.
  • block_ms: wie lange auf das Eintreffen von Arbeit gewartet werden soll, bevor zurückgekehrt wird, in Millisekunden. Muss zwischen 1 und 999 liegen (Wartezeit pro Poll; der Helfer pollt automatisch erneut). Übergib null (None in Python, param.Null[int64]() in Go) für eine nicht-blockierende Prüfung; das Weglassen des Parameters verwendet den Standard-Long-Poll von 999 ms.
  • reclaim_older_than_ms: beansprucht Work-Items erneut, die beansprucht, aber innerhalb dieser Anzahl von Millisekunden nie bestätigt wurden.
  • auto_stop: ob für jedes Work-Item ein Stoppsignal gesendet werden soll, sobald dein Schleifenkörper damit fertig ist. Der Go-Poller hat kein Opt-out und sendet das Stoppsignal immer; blockiere daher im Schleifenkörper, bis die Session abgeschlossen ist, statt dich abzukoppeln.
• client.beta.sessions.events.tool_runner(): führt Tool-Aufrufe für eine einzelne Session aus, gegeben die Session-ID und eine Tool-Liste. Verwende dies, wenn du die Arbeit bereits beansprucht hast und nur die Ausführungsschicht benötigst.

Verwende den Work-Poller direkt, wenn du deinen eigenen Prozess pro Session starten möchtest, zum Beispiel das Hochfahren einer Sandbox für jede beanspruchte Session:

import asyncio
import os

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


async def launch_container(work: BetaSelfHostedWork) -> None:
    # Ersetze dies durch deinen eigenen Sandbox-Launcher pro Session. Übergib
    # ANTHROPIC_ENVIRONMENT_KEY an die gestartete Sandbox, niemals
    # deinen API-Key.
    print(f"claimed session {work.data.id}")


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())

AgentToolContext ist der Ausführungskontext für Tool-Aufrufe. Er definiert das Arbeitsverzeichnis und die Pfadrichtlinie und kann die Skills der Session herunterladen. beta_agent_toolset_20260401(env) nimmt einen AgentToolContext entgegen und gibt die Standard-Tool-Implementierungen zurück (bash, read, write, edit, glob, grep).

Mit EnvironmentWorker: Beide werden automatisch verwaltet. Übergib eine tools-Factory, um die Tool-Liste anzupassen:

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

Mit work.poller() und tool_runner(): Übergib eine Tool-Liste als tools an client.beta.sessions.events.tool_runner(). Um diese Liste zu erstellen, richte AgentToolContext selbst ein und rufe beta_agent_toolset_20260401(env) auf:

from anthropic.lib.tools.agent_toolset import (
    AgentToolContext,
    beta_agent_toolset_20260401,
)

async with AgentToolContext(
    workdir="/workspace", client=client, session_id=work.data.id
) as env:
    # Skills heruntergeladen nach /workspace/skills/<name>/
    tools = beta_agent_toolset_20260401(env)



Überprüfe, ob der Worker verbunden ist

Bestätige von einer separaten Shell aus, mit ANTHROPIC_API_KEY auf deinen Claude-API-Key gesetzt (nicht den Environment-Key), dass workers_polling mindestens 1 ist:

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

Wenn workers_polling bei 0 bleibt, erreicht der Worker die Warteschlange nicht: Bestätige, dass ANTHROPIC_ENVIRONMENT_KEY und ANTHROPIC_ENVIRONMENT_ID auf dem Worker-Host gesetzt sind. Siehe Warteschlangentiefe lesen für die vollständige Stats-Antwort und weitere Sprachbeispiele.



Eine Session starten

Sobald dein Worker läuft, erstelle eine Session, die auf die Umgebung abzielt. Setze AGENT_ID auf die Agent-ID, die du dir in Bevor du beginnst notiert hast. Die Session tritt in die Arbeitswarteschlange der Umgebung ein und wartet dort, bis ein Worker sie beansprucht; wenn kein Worker verbunden ist, bleibt die Session in der Warteschlange, statt fehlzuschlagen.

Anthropic mountet keine Dateien oder GitHub-Repositories in selbst gehostete Sandboxes. Um sessionspezifische Dateien verfügbar zu machen, übergib Dateireferenzen (wie einen S3-Pfad oder Commit-SHA) im metadata-Feld der Session. Dein Spawn-Skript oder --on-work-Handler liest diese Metadaten aus dem beanspruchten Work-Item (der CLI-Poller leitet das JSON des Work-Items an die Standardeingabe des Skripts weiter, und SDK-Handler können es über die Environments-Work-Endpunkte lesen) und stellt die Dateien im Arbeitsverzeichnis bereit, bevor die Tool-Ausführung beginnt.

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

Siehe Selbst gehosteter Worker in der Referenz für die vollständige Liste der CLI-Flags und SDK-Helfer für die SDK-Helfer-Optionen.



Monitoring und Betrieb

Diese Aufrufe laufen von deinem Monitoring- oder Betriebs-Tooling aus, authentifiziert mit deinem Claude-API-Key, um die Worker-Flotte zu beobachten und zu verwalten. Die Claim- und Keep-Alive-Schleife wird innerhalb der Worker-Helfer abgewickelt, sodass du diese Endpunkte nicht direkt aufrufst.



Warteschlangentiefe lesen

work.stats gibt den Warteschlangenzustand für eine Umgebung zurück:

• depth ist die Anzahl der Items, die darauf warten, beansprucht zu werden. Skaliere deine Worker-Flotte oder alarmiere bei Rückstau basierend auf diesem Wert.
• pending ist die Anzahl der Items, die ein Worker beansprucht hat und gerade verarbeitet.
• oldest_queued_at ist der Zeitstempel des ältesten Items, das noch in der Warteschlange steht oder verarbeitet wird, oder null, wenn es keines gibt.
• workers_polling ist die Anzahl der Worker, die in den letzten 30 Sekunden gepollt haben. Verwende dies für Liveness-Alarmierung.

import os

import anthropic

client = anthropic.Anthropic()

stats = client.beta.environments.work.stats(os.environ["ANTHROPIC_ENVIRONMENT_ID"])
print(f"depth={stats.depth} pending={stats.pending}")

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



Eine Session ordnungsgemäß stoppen

Verwende work.stop, um den Worker, der eine bestimmte Session bearbeitet, zu bitten, sie sauber herunterzufahren. Der Worker beendet alle laufenden Tool-Aufrufe, sendet einen finalen Status und gibt die Session frei. Übergib force: true im Request-Body (mit der CLI übergib --force), um sofort zu unterbrechen, statt auf den Abschluss des aktuellen Tool-Aufrufs zu warten.

Da diese Aufrufe von deinem Betriebs-Tooling und nicht vom Worker-Host aus laufen, wird ANTHROPIC_WORK_ID nicht automatisch gesetzt. Setze es auf die ID des Ziel-Work-Items, bevor du die folgenden Beispiele ausführst. Um die ID eines Work-Items zu finden, liste die Work-Items der Umgebung über die Environments-Work-Endpunkte auf.

import os

import anthropic

client = anthropic.Anthropic()

work = client.beta.environments.work.stop(
    os.environ["ANTHROPIC_WORK_ID"],
    environment_id=os.environ["ANTHROPIC_ENVIRONMENT_ID"],
)
print(work.state)



Nächste Schritte