Einrichtung der Cloud-Umgebung

Environments (Umgebungen) definieren die Sandbox-Konfiguration, in der dein Agent läuft. Du erstellst eine Umgebung einmal und referenzierst dann ihre ID jedes Mal, wenn du eine Session startest. Mehrere Sessions können dieselbe Umgebung gemeinsam nutzen, aber jede Session erhält ihre eigene isolierte Sandbox (einen frischen Linux-Container).

Diese Seite behandelt Umgebungen vom Typ type: cloud. Um Sandboxes auf deiner eigenen Infrastruktur auszuführen, siehe Selbst gehostete Sandboxes. Um zwischen beiden zu wählen, siehe Eine Agent-Umgebung auswählen.

Eine Umgebung erstellen

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: python-dev
config:
  type: cloud
  networking:
    type: limited
    allow_package_managers: true

Verwende einen eindeutigen, aussagekräftigen name, damit du Umgebungen auseinanderhalten kannst. Dieses Beispiel verwendet limited Networking mit erlaubten Paketmanagern, sodass die Sandbox die Paket-Registries und Code-Hosts erreichen kann. Damit sie andere Hosts erreichen kann, füge diese zu allowed_hosts hinzu.

Die Umgebung in einer Session verwenden

Übergib die Umgebungs-ID als String beim Erstellen einer Session.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

Konfigurationsoptionen

Pakete

Das Feld packages installiert Pakete in der Sandbox vor, bevor der Agent startet. Pakete werden von ihren jeweiligen Paketmanagern installiert und über Sessions hinweg zwischengespeichert, die dieselbe Umgebung nutzen. Wenn mehrere Paketmanager angegeben sind, laufen sie in alphabetischer Reihenfolge (apt, cargo, gem, go, npm, pip). Optional kannst du bestimmte Versionen festlegen. Pakete ohne festgelegte Version installieren die neueste Version. Wenn die Umgebung limited Networking verwendet, setze außerdem allow_package_managers in networking auf true; andernfalls wird die Anfrage mit einem 400-Fehler abgelehnt.

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: data-analysis
config:
  type: cloud
  packages:
    pip:
      - pandas
      - numpy
      - scikit-learn
    npm:
      - express
  networking:
    type: limited
    allow_package_managers: true

Unterstützte Paketmanager:

Networking

Das Feld networking steuert den ausgehenden Netzwerkzugriff der Sandbox.

Bei limited Networking gilt allowed_hosts auch für die Tools web_search und web_fetch, die auf den Servern von Anthropic laufen. Ein web_fetch-Aufruf für eine URL auf einem Host, auf den allowed_hosts nicht zutrifft, gibt dem Agenten ein Fehlerergebnis zurück. web_search lässt Ergebnisse von Hosts weg, auf die allowed_hosts nicht zutrifft. allow_package_managers und allow_mcp_servers fügen für diese Tools keine Hosts hinzu. Wenn allowed_hosts keine Hosts auflistet, gibt kein web_fetch- oder web_search-Aufruf eine Seite oder ein Suchergebnis zurück. Ein Host, den du für diese Tools zu allowed_hosts hinzufügst, ist auch für die Sandbox offen. unrestricted Networking und selbst gehostete Umgebungen schränken diese Tools nicht ein. Um sie weiter einzuschränken, setze allowed_domains oder blocked_domains im Eintrag des Tools im Agent-Toolset. Siehe Domains für Websuche und Web-Fetch einschränken.

Das folgende Beispiel erstellt eine Umgebung mit limited Networking:

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: api-access
config:
  type: cloud
  networking:
    type: limited
    allowed_hosts:
      - api.example.com
    allow_mcp_servers: true
    allow_package_managers: true

Mit limited Networking und ohne weitere gesetzte Felder sind keine Hosts erlaubt. Dateien, Memory Stores und GitHub-Repositories, die du an die Session anhängst, bleiben verfügbar. Wenn eine Anfrage aus der Sandbox auf Port 80 oder 443 abgelehnt wird, weil ihr Host nicht erlaubt ist, ist die Antwort ein 403, der den blockierten Host nennt.

Bei Verwendung von limited Networking:

• allowed_hosts gibt Domains an, die die Sandbox erreichen kann. Gib reine Hostnamen oder Wildcard-Muster (wie *.example.com) an. Füge kein URL-Schema, keinen Port und keinen Pfad hinzu. Ein reiner Hostname trifft genau auf diesen Host zu: example.com trifft nicht auf www.example.com zu. *.example.com trifft auf jede Subdomain von example.com zu, aber nicht auf example.com selbst.
• allow_mcp_servers erlaubt ausgehenden Zugriff auf MCP-Server-Endpunkte, die im Agenten konfiguriert sind, über die im Array allowed_hosts aufgeführten hinaus. Standardwert ist false. Solange es false ist, schlägt die Session-Erstellung mit einem 400-Fehler fehl, wenn der Agent einen MCP-Server deklariert, dessen Host nicht in allowed_hosts enthalten ist. Dasselbe gilt für einen Agenten, an den er delegieren kann. Um das zu beheben, füge den Host zu allowed_hosts hinzu oder setze allow_mcp_servers auf true.
• allow_package_managers erlaubt ausgehenden Zugriff auf eine Reihe öffentlicher Paket-Registries und Code-Hosts über die im Array allowed_hosts aufgeführten hinaus. Die Liste findest du unter Paketmanager-Hosts. Standardwert ist false. Setze es auf true, wann immer die Umgebung packages angibt; andernfalls wird die Anfrage mit einem 400-Fehler abgelehnt, selbst wenn die Registry-Hosts in allowed_hosts aufgeführt sind.

Paketmanager-Hosts

Wenn allow_package_managers true ist, kann die Sandbox zusätzlich zu den Hosts in allowed_hosts die folgenden Hosts erreichen. Anthropic pflegt diese Liste und kann sie ändern.

Risiken von uneingeschränktem Networking

Mit unrestricted Networking kann Code in der Sandbox Anfragen an jeden Host im Internet senden, mit Ausnahme von Hosts auf einer allgemeinen Sicherheits-Blocklist. Bevor du diesen Modus wählst, überlege, was der Agent mit diesem Zugriff tun kann:

• Der Agent kann Dinge auf externen Websites ändern, nicht nur lesen: Das bash-Tool kann jede beliebige Anfrage senden. Der Agent kann Daten posten, Formulare absenden, APIs aufrufen und Skripte ausführen, die Daten auf externen Websites ändern. Selbst eine Anfrage, die nur eine URL abruft, kann auf manchen Websites Daten ändern.
• Standardmäßig hält nichts diese Anfragen an: Die Standard-Berechtigungsrichtlinie des Agent-Toolsets ist always_allow, sodass bash-Befehle ohne Genehmigung ausgeführt werden.
• Alles in der Sandbox kann sie verlassen: Dazu gehören Dateien, Tool-Ausgaben und alle Anmeldedaten oder Secrets, die du in die Sandbox legst.
• Abgerufene Inhalte können den Agenten steuern: Webseiten, API-Antworten und andere Inhalte, die der Agent liest, können Anweisungen enthalten (Prompt-Injektion), die ändern, was er als Nächstes tut.
• Der Agent handelt in deinem Namen: Seine Aktionen können gegen die Nutzungsbedingungen einer Website verstoßen oder dort Konten und Datensätze anlegen.
• Modellverhalten ist keine Sicherheitskontrolle: Der Agent kann auf externen Websites auf eine Weise handeln, um die du nicht gebeten hast, einschließlich eines erneuten Versuchs auf andere Weise, nachdem eine Website eine Anfrage blockiert hat. Verwende Netzwerkeinstellungen und Berechtigungsrichtlinien, um einzuschränken, was er tun kann.
• Die Sicherheits-Blocklist ist keine Allowlist: Sie schränkt nicht ein, welche anderen Websites der Agent erreicht oder was der Agent auf ihnen tut.

Um diese Risiken zu verringern, verwende limited Networking mit einer expliziten Liste von Hosts. Der folgende networking-Wert erlaubt api.example.com sowie die Paketmanager-Hosts für einen Agenten, der Pakete installiert:

{
  "type": "limited",
  "allowed_hosts": ["api.example.com"],
  "allow_package_managers": true
}

Ein Agent, der nur die Tools web_search und web_fetch verwendet, benötigt kein unrestricted Networking, wenn du die Websites auflisten kannst, die er braucht. Bei limited Networking gilt allowed_hosts auch für diese Tools (siehe Networking), also liste diese Websites in allowed_hosts auf. Wenn du sie zusätzlich in allowed_domains von web_search auflistest, durchsucht es diese Websites. Ein Host, den du zu allowed_hosts hinzufügst, ist auch für die Sandbox offen. Um die Tools weiter einzuschränken, siehe Domains für Websuche und Web-Fetch einschränken.

Verwende unrestricted nur, wenn der Agent Websites erreichen muss, die du nicht im Voraus auflisten kannst. Halte in diesem Fall Secrets und sensible Dateien aus der Sandbox heraus und gib dem Agenten nur die Anmeldedaten, die die Aufgabe benötigt. Erwäge, die Berechtigungsrichtlinie des bash-Tools auf always_ask oder auto zu setzen, und beobachte die Events der Session.

Lebenszyklus von Umgebungen

• Umgebungen bleiben bestehen, bis sie explizit archiviert oder gelöscht werden.
• Jede Session erhält ihre eigene Sandbox-Instanz, auch wenn mehrere Sessions dieselbe Umgebung referenzieren. Sessions teilen keinen Dateisystemzustand.
• Umgebungen sind nicht versioniert. Wenn du eine Umgebung häufig aktualisierst, führe deine eigenen Aufzeichnungen über die Änderungen, damit du nachvollziehen kannst, welche Konfiguration jede Session verwendet hat.

Umgebungen verwalten

# Liste Umgebungen auf
environments = client.beta.environments.list()

# Rufe eine bestimmte Umgebung ab
env = client.beta.environments.retrieve(environment.id)

# Archiviere eine Umgebung (schreibgeschützt, bestehende Sitzungen laufen weiter)
client.beta.environments.archive(environment.id)

# Lösche eine Umgebung (nur wenn keine Sitzungen darauf verweisen)
client.beta.environments.delete(environment.id)

Vorinstallierte Laufzeitumgebungen

Cloud-Sandboxes enthalten standardmäßig gängige Sprach-Laufzeitumgebungen, Datenbanken und Kommandozeilen-Tools. Siehe Cloud-Sandbox-Referenz für die vollständige Liste.

Nächste Schritte