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 aber die Tool-Ausführung in von dir kontrollierte Infrastruktur, sodass der Code des Agents, das Dateisystem und der ausgehende Netzwerkverkehr 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 an Anthropics Control Plane (wo Claude läuft), damit das Modell die Ergebnisse sehen und entscheiden kann, was als Nächstes zu tun ist. Siehe das Sicherheitsmodell für die vollständige Datenflussgrenze.

Unterschiede zu Cloud-Umgebungen

Self-Hosting eignet sich gut, 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-Eignung siehe API und Datenspeicherung.

Wann du MCP-Tunnel kombinieren solltest

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

Environment Worker

Ein „environment worker" (Umgebungs-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, erzeugt für jedes einen Ausführungskontext, lädt die Skills des Agents herunter (wiederverwendbare, dateisystembasierte Ressourcen, die dem Agent domänenspezifisches Fachwissen verleihen), 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.

Sowohl die CLI als auch das SDK liefern 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 Self-hosted Worker in der Referenz für CLI-Flags und SDK-Helper auf dieser Seite für die SDK-Optionen. Für mehr Kontrolle rufe die Environments-Work-Endpunkte direkt auf und implementiere deinen eigenen Worker. Auf Claude Platform on AWS ist der List-Endpunkt GET /v1/environments/{id}/work und sein SDK-Äquivalent derzeit nicht verfügbar; die anderen Work-Endpunkte (poll, ack, heartbeat, stop, post results, per-item get und stats) funktionieren normal.

Sandbox-Dateisystem

• /workspace: das systemweite 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: das Worker-Harness weist Claude an, finale Ergebnisse hier abzulegen. Im Sandbox-Modus mounte ein Host-Verzeichnis an diesem Pfad, um Ausgaben nach Ende der Session abzurufen. Im In-Process-Modus schreiben die Datei-Tools des Workers stattdessen unterhalb des Arbeitsverzeichnisses, sodass dieser Pfad nicht gilt.

Bevor du beginnst

Du benötigst:

• Einen bestehenden Agent. Wenn du keinen hast, schließe zuerst den Quickstart ab und notiere dir seine Agent-ID.
• Einen Linux-Host mit /bin/bash an genau diesem Pfad. Das TypeScript-SDK benötigt zusätzlich unzip, tar und Node.js 22 oder höher; das Python-SDK verwendet die Standardbibliothek für die Archivextraktion und hat keine zusätzlichen Binäranforderungen. Diese Abhängigkeiten werden an festen Pfaden aufgelöst und berücksichtigen keine PATH-Overrides.
• Die ant-CLI oder ein Anthropic-SDK (Python, TypeScript oder Go) auf dem Worker-Host.
• Zwei Anmeldedaten: Ein Environment Key (wird in den folgenden Schritten generiert) authentifiziert den Worker gegenüber seiner Warteschlange; dein Claude-API-Key erstellt Sessions und liest Warteschlangenstatistiken von außerhalb des Worker-Hosts.

Einen Worker ausführen

Wähle Always-on für das einfachste Setup: Ein lang laufender 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-Einrichtung und Signaturverifizierung).

SDK-Helper

Das SDK bietet drei Helper auf unterschiedlichen Kontrollebenen. EnvironmentWorker deckt die meisten Anwendungsfälle ab; greife auf die Low-Level-Helper 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. Beendet sich sauber bei SIGTERM.
  • .handle_item(): nimmt eine ausstehende Session auf, bearbeitet sie und beendet sich.
• work.poller(): pollt die Arbeitswarteschlange für dich und übergibt dir jede beanspruchte Session. Verwende dies, wenn du entscheiden möchtest, was für jede Session passiert, zum Beispiel eine Sandbox starten statt Tools in-process auszuführen.
  • drain: ob das Polling gestoppt werden soll, sobald die Warteschlange leer ist, anstatt auf neue Arbeit zu warten.
  • block_ms: wie lange auf eintreffende Arbeit gewartet werden soll, bevor zurückgekehrt wird, in Millisekunden. Muss zwischen 1 und 999 liegen (Wartezeit pro Poll; der Helper pollt automatisch erneut). Übergib null (None in Python, param.Null[int64]() in Go) für eine nicht-blockierende Prüfung; wird der Parameter weggelassen, wird der Standard-Long-Poll von 999 ms verwendet.
  • reclaim_older_than_ms: beanspruche Work Items erneut, die an einen Worker vergeben wurden, der nicht mehr antwortet.
  • auto_stop: ob nach dem Beenden des Iterators ein Stop-Signal für das Work Item gesendet werden soll. Der Go-Poller hat kein Opt-out und sendet das Stop-Signal immer, blockiere also im Schleifenkörper, bis die Session abgeschlossen ist, anstatt 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 eine Sandbox für jede beanspruchte Session hochfahren:

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 sitzungsbezogenen Sandbox-Launcher. Ü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 lädt optional die Skills der Session herunter, wenn er als Context Manager verwendet wird. 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: beides wird 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 downloaded to /workspace/skills/<name>/
    tools = beta_agent_toolset_20260401(env)

Überprüfe, ob der Worker verbunden ist

Bestätige von einer separaten Shell aus mit deinem Claude-API-Key (nicht dem 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 auslesen für die vollständige Stats-Antwort und Beispiele in anderen Sprachen.

Eine Session starten

Sobald dein Worker läuft, erstelle eine Session, die auf die Umgebung abzielt. Die Session gelangt in die Arbeitswarteschlange der Umgebung und wartet dort, bis ein Worker sie beansprucht; wenn kein Worker verbunden ist, bleibt die Session in der Warteschlange, anstatt 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 (über die Environments-Work-Endpunkte) 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 Self-hosted Worker in der Referenz für die vollständige Liste der CLI-Flags und SDK-Helper für die SDK-Helper-Optionen.

Monitoring und Betrieb

Diese Aufrufe laufen von deinem Monitoring- oder Operations-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-Helper abgewickelt, sodass du diese Endpunkte nicht direkt aufrufst.

Warteschlangentiefe auslesen

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 in der Warteschlange oder null, wenn die Warteschlange leer ist.
• workers_polling ist die Anzahl der Worker, die in den letzten 30 Sekunden gepollt haben. Verwende dies für Liveness-Alerting.

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 sauber stoppen

Verwende work.stop, um den Worker, der eine bestimmte Session bearbeitet, aufzufordern, sie sauber herunterzufahren. Der Worker beendet jeden laufenden Tool-Aufruf, sendet einen finalen Status und gibt die Session frei. Übergib force: true im Request-Body, um sofort zu unterbrechen, anstatt auf den Abschluss des aktuellen Tool-Aufrufs zu warten.

Da diese Aufrufe von deinem Operations-Tooling und nicht vom Worker-Host aus laufen, ist ANTHROPIC_WORK_ID nicht automatisch gesetzt. Setze sie auf die ID des Ziel-Work-Items, bevor du die folgenden Beispiele ausführst.

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