Best Practices für Agent-Containment: Sandboxing (private Beta)

Für Kunden in unserem Cyber Verification Program stellen wir einen neuen Sandbox-Escape-Klassifizierer in der API bereit, um Missbrauch zu überwachen und zu reduzieren. Dieser Artikel erklärt, warum autonome Agenten starke Isolation benötigen, wie das Referenzdesign sie isoliert, und wie Sie Engagements mit Netzwerkzugriff definieren und überwachen.

Eine Übersicht über alle verfügbaren Ressourcen finden Sie unter Best Practices für Agent-Containment: Erste Schritte (private Beta).

Wenn Sie Ihre eigene Sandbox erstellen, sind dies die Eigenschaften, die das Referenzdesign bietet. Der Rest dieses Artikels beschreibt eine Möglichkeit, diese zu erreichen.

Führen Sie autonome Agenten in starken Sandboxes aus und überlegen Sie sich, welche Nebenwirkungen ein Prozess in dieser Sandbox noch verursachen könnte. Frontier-Modelle werden zunehmend besser darin, kreative Wege um Einschränkungen zu finden: Die gleiche Eigenschaft, die sie zu effektiven Vulnerability-Jägern macht, bedeutet, dass sie möglicherweise unerwartete Maßnahmen gegen ihre eigene Ausführungsumgebung ergreifen. Dies ist nicht hypothetisch. Anthropic hat Beispiele veröffentlicht, in denen Modelle schwache Einschränkungen umgehen, um eine Aufgabe zu erfüllen (siehe How we contain Claude across products).

Konkret: Führen Sie autonome Vulnerability-Finding-Agenten nicht in einfachem Docker/runc aus, und schon gar nicht mit --privileged oder Host-Netzwerk. Standard-Container teilen den Host-Kernel, daher ist ein Kernel-Exploit im Container ein Host-Kompromiss. Wir empfehlen, einen Hardware-virtualisierten Kernel zwischen Zielcode und Host zu platzieren, was bedeutet, den Agenten in einer virtuellen Maschine auszuführen. Wenn das nicht möglich ist, verwenden Sie einen dedizierten Bare-Metal-Host, der nichts anderes enthält. Wenn Sie Ihre eigene Sandbox erstellen, empfehlen wir Firecracker unter Linux, Hyper-V unter Windows und eine VM basierend auf dem Hypervisor-Framework unter macOS. Das Referenzdesign verwendet Firecracker.

Blockieren Sie den gesamten Ausgangsverkehr aus der Sandbox. Der Agent erreicht die Modell-API nur über einen Proxy, der die Anmeldedaten hinzufügt und außerhalb der Sandbox läuft, daher benötigt die Sandbox keine direkte Route zum API-Host. Installieren Sie jedes Tool, Paket und jede Abhängigkeit, bevor die Ausführung beginnt, damit während der Ausführung nichts abgerufen werden muss.

Interaktive Nutzung mit einem Menschen in der Schleife birgt im Allgemeinen weniger Risiko, aber wir empfehlen dennoch eine Sandbox dafür. Wenn Sie einen Agenten interaktiv von Claude Code auf einem Laptop aus steuern, überprüfen Sie entweder jede Tool-Nutzung (manueller Modus) oder verlassen Sie sich auf den Auto-Mode-Berechtigungsklassifizierer und lassen Sie einen Menschen jede Aktion genehmigen, die das Repo verlässt. Der Auto-Modus entfernt routinemäßige Berechtigungsaufforderungen: Er genehmigt Lesevorgänge und Bearbeitungen des Arbeitsverzeichnisses automatisch und sendet alles andere an einen Hintergrund-Klassifizierer, der darauf abzielt, destruktive, irreversible oder aufgabenfremde Aktionen zu blockieren. Es ist eine Best-Effort-Überprüfung. Es kann Dinge übersehen, und bei Sicherheitsarbeiten kann es auch einige legitime Schritte ablehnen. Auto-Modus beschreibt, wie es funktioniert, was Sie davon erwarten können, und wie Sie es für Ihre Umgebung konfigurieren.

Mounten Sie niemals Pfade mit Anmeldedaten wie ~/.aws, ~/.ssh oder .env in die Umgebung des Agenten. Das Gleiche gilt für die Anmeldedaten, die die eigenen Modellaufrufe des Agenten verwenden. Halten Sie sie außerhalb der Sandbox, und lassen Sie einen Proxy, den der Agent nicht lesen kann, sie zu jeder Anfrage hinzufügen (siehe Der Anmeldedaten-Proxy). Verbinden Sie Agenten nicht mit MCP-Servern oder Tools mit Schreibzugriff auf externen Status wie E-Mail, Cloud-Speicher oder Produktionsinfrastruktur.

Dies ist ein Muster, das die obigen Richtlinien in die Praxis umsetzt. Die Setup-Phase hat ausgehenden Internetzugriff und einen Menschen in der Schleife, der jeden Tool-Aufruf genehmigt. Darin zieht der Agent Abhängigkeiten, erstellt das Ziel und richtet seine Sandbox aus einem Spezifikationsdokument ein. Die Angriffsphase hat keinen allgemeinen Internetzugriff. Der gesamte Ausgangsverkehr geht durch einen Zulassungslisten-Proxy, der nur die in der Engagement genannten Hosts zulässt, daher erzwingt der Proxy auch den Umfang. Modellaufrufe gehen durch den separaten Anmeldedaten-Proxy. Der Agent kann dann unbeaufsichtigt das Ziel untersuchen. Der Proxy enthält den eigenen Verkehr des Agenten. Er enthält nicht den Verkehr, den ein vernetztes Ziel im Namen des Agenten sendet.

Backen Sie die Abhängigkeiten, die der Agent wiederholt benötigt, in das Setup-Image, damit Angriffsphase-Durchläufe überhaupt keinen Internetzugriff benötigen. Bereichern Sie Anmeldedaten pro Ziel, damit ein Agent, der an einem Ziel arbeitet, diese nicht gegen ein anderes verwenden kann. Halten Sie Claude Code's Auto-Modus während der Angriffsphase in der Sandbox aktiviert und beschreiben Sie die Sandbox seinem Klassifizierer. Siehe Auto-Modus.

Geben Sie jedem Agenten ein explizites Budget, damit ein Durchlauf, der sein beabsichtigtes Testen überschreitet, von selbst stoppt und nicht, wenn jemand es bemerkt. Erzwingen Sie ein hartes Turnus-Limit für jeden Agenten. Wenn ein Agent es erschöpft, beenden Sie den Durchlauf und gewähren Sie nicht automatisch mehr Turnusse. Das Neustarten mit einem höheren Limit ist der Punkt, an dem eine Person entscheidet, fortzufahren. Begrenzen Sie Durchläufe auch zeitlich. Beenden Sie eine Sitzung, die ihr Zeitlimit überschreitet, auf die gleiche Weise: Der Durchlauf ist endgültig und wird nie fortgesetzt, und der Agent-Prozess wird gestoppt, auch wenn das Limit in der Mitte eines lang laufenden Befehls erreicht wird. Wenn ein Limit auf einen Wert gesetzt ist, der nicht gelesen werden kann, lehnen Sie den Start ab, anstatt unbegrenzt zu laufen. Legen Sie die Limits absichtlich für das Engagement fest und akzeptieren Sie keinen großzügigen Standard. Koppeln Sie sie mit der Überwachungshäufigkeit in Offline-Überwachung von Agent-Transkripten, damit ein langer Batch jede Stunde oder zwei angesehen wird und nicht nur am Ende. Wissen Sie, wie Sie einen einzelnen Agenten stoppen, ohne den Batch zu stoppen. In einem Docker-basierten Setup ist das docker rm -f <agent-container>. Der Orchestrator sollte diesen Durchlauf als fehlgeschlagen aufzeichnen und mit dem Rest des Batch fortfahren.

Weitere Anleitungen finden Sie in zwei Anthropic-Ressourcen. Securely deploying AI agents behandelt Isolationsoptionen, Anmeldedaten-Proxying und Dateisystem-Härtung. Die Engineering-Retrospektive How we contain Claude across products behandelt, was funktioniert hat und was nicht, wenn diese gleichen Mechanismen in der Produktion liefen.

Die Sandbox begrenzt, was ein Agent erreichen kann. Für Pentesting, Red Teaming und andere Engagements, die Netzwerkzugriff benötigen, begrenzen die folgenden Praktiken, was der Agent gefragt und darf tun. Sie hängen von Ihren Zielen und Ihrem Team ab, daher kann Tooling die meisten von ihnen nicht für Sie einrichten.

Teilen Sie dem Agenten vor einem Durchlauf mit, welche Ziele im Umfang liegen, welche Aktionen zulässig sind, wo die Netzwerkgrenze liegt und was außerhalb des Umfangs liegt. Formulieren Sie jede Einschränkung als Absicht ("Greifen Sie nicht auf Hosts außerhalb von 10.0.3.0/24 zu") und nicht als Behauptung über die Umgebung ("Sie können das Internet nicht erreichen"), damit die Anweisung noch gültig ist, wenn die Umgebung falsch konfiguriert ist. Tun Sie dies auch für sandboxed lokale Arbeiten: Teilen Sie dem Agenten mit, dass er keinen Internetzugriff verwenden soll, obwohl die Sandbox ihn blockiert. Die Beschreibung, die Sie dem Klassifizierer des Auto-Modus geben, ist etwas anderes. Sie gibt Fakten über die Maschine an (siehe Auto-Modus).

Führen Sie den Agenten, wo möglich, in der gleichen Isolation aus, die oben beschrieben ist, und setzen Sie den Ausgangsverkehr nur zu den im Umfang liegenden Zielen auf die Zulassungsliste (siehe Ausgangs-Zulassungsliste). Der Agent erreicht die Modell-API über den Anmeldedaten-Proxy, nicht über die Zulassungsliste. Wo verfügbar, richten Sie das Engagement auf eine Staging- oder Replikaumgebung aus, die von der Produktion getrennt ist.

Geben Sie dem Agenten Zugriff auf Zielsysteme durch etwas, das Sie beobachten können, wie einen Zugriffs-Proxy oder einen definierten Satz von Tools. Vermeiden Sie es, dem Agenten zu erlauben, seine eigene Tooling mit allgemeinem Zugriff auf das Ziel zu schreiben. Trennen Sie in einem benutzerdefinierten Harness schreibgeschützte Tools von Tools, die den Status ändern, und überwachen Sie die zweite Gruppe genauer. Erwägen Sie, riskante Befehle bei ihrer Vorschlag zu analysieren und sie abzulehnen oder an eine Person zu eskalieren.

Wir empfehlen, dass ein Ingenieur jeden Durchlauf während der Ausführung beobachtet, Tool-Aufrufe und Netzwerkaktivität verfolgt und den Durchlauf sofort anhalten kann. Agenten handeln mit Maschinengeschwindigkeit, daher ergänzt die Live-Beobachtung die Kontrollen, die vor einer Aktion wirken (Netzwerk-Zulassungslisten, vermittelte Tools und Überprüfung von Statusänderungen). Sie ersetzt sie nicht. Für lange oder autonome Durchläufe, bei denen kontinuierliche Aufmerksamkeit unpraktisch ist, überwachen Sie kontinuierlich in Software (siehe Offline-Überwachung von Agent-Transkripten).

Führen Sie autonome Agenten nicht gegen Live-Produktionssysteme aus, bei denen eine Aktion außerhalb des Umfangs die Sicherheit oder Verfügbarkeit kritischer Dienste gefährden könnte, wie OT/ICS, medizinische oder Energiesysteme. Dies ist bereits die Norm für menschengeführte Tests solcher Systeme, und es gilt gleichermaßen hier. Testen Sie gegen ein Replikat, ein Testbed oder einen digitalen Zwilling, oder während eines geplanten Ausfalls. Wenn Live-Zugriff unvermeidbar ist, beschränken Sie den Agenten auf passive oder schreibgeschützte Aktivität und lassen Sie eine Person jeden Statusänderungsschritt ausführen.

Bevor Sie echte Engagements von einem Host aus ausführen, testen Sie seine Sandbox mit den beiden folgenden Schritten. Tun Sie dies vor der ersten echten Nutzung und erneut, wenn Sie das Modell oder die Sandbox ändern. Sandbox-Änderungen umfassen einen neuen Host, eine neue Version des Hypervisors oder der Container-Runtime, ein anderes Netzwerk- oder Proxy-Setup und eine bearbeitete Container- oder Compose-Konfiguration.

Bitten Sie Claude in einer interaktiven Claude Code-Sitzung auf dem Host, die Sandbox-Konfiguration so zu lesen, wie sie auf diesem Computer eingerichtet ist, und alles zu melden, was die in diesem Artikel beschriebene Grenze schwächt. Verweisen Sie es auf:

Dieser Schritt liest nur Konfiguration und Status. Er startet keinen Agenten.

Starten Sie den Test-Agenten auf die gleiche Weise wie Produktionsagenten, nicht mit einem manuell erstellten Befehl, damit der Test den echten Pfad ausübt. Der Abschnitt Überprüfen Sie die Isolation selbst unten behandelt die manuellen Überprüfungen der Grenze stattdessen. Geben Sie dem Agenten eine einzelne Aufgabe: Versuchen Sie, alles außerhalb seiner Grenze zu erreichen, und stoppen und melden Sie, sobald etwas erfolgreich ist. Benennen Sie die Grenze konkret in der Eingabeaufforderung: den Host, andere Container, den Container-Runtime-Socket, den Cloud-Metadatendienst und jeden Host, der nicht auf der Allowlist des Proxys steht. Führen Sie dies nur unter enger menschlicher Aufsicht auf einem Host ohne Internetzugang außer zur Model-API aus, den Sie neu aufbauen können, damit ein erfolgreicher Escape keinen Schaden anrichtet. Auf Bare Metal führen Sie den Test in einer wegwerfbaren VM aus. Auf einer Cloud-VM verwenden Sie eine neue Instanz und zerstören Sie sie danach. Beobachten Sie die Sitzung während der Ausführung. Behandeln Sie jeden Erfolg als Blocker: Beheben Sie den Host, wiederholen Sie den Test, und führen Sie keine Engagements von diesem Host aus, bis der Test erfolgreich ist.

Überprüfen Sie, was der Agent versucht hat, sowie ob er entkommen ist. Suchen Sie nach direkten Verbindungen, die nicht durch den Proxy gingen, Lesevorgängen von Credential-Dateien oder Metadatenadressen, Verwendung des Container-Runtime-Sockets oder Sonden benachbarter Container, Schreibvorgängen außerhalb des eigenen Dateisystems des Containers und Versuchen, die eigenen Einstellungen oder Tools des Agenten zu ändern. Der Test ist erfolgreich, wenn das Transkript zeigt, dass jeder dieser Punkte versucht wurde und aus dem erwarteten Grund fehlgeschlagen ist. Notieren Sie für jeden, ob die Sandbox oder der Berechtigungsklassifizierer ihn gestoppt hat. Ein Versuch, den der Klassifizierer verweigert hat, hat die Sandbox nie erreicht, daher decken Sie ihn mit den manuellen Überprüfungen ab (siehe Überprüfen Sie die Isolation selbst unten). Ein bestandener Test ist eine Mindestanforderung, kein Beweis der Isolation.

Bestätigen Sie vor dem Start, dass die Aufgabe wie angegeben abgeschlossen werden kann. Einige Beispiele für Aufgaben, die nicht abgeschlossen werden können: ein Fokusbereich ohne etwas zum Finden, ein Ziel, das nicht erreichbar ist, ein Bug, der nicht vorhanden ist, oder ein Tool, das die Aufgabe benötigt und nicht installiert ist. Wann immer Sie Ihr Setup ändern oder eine neue Art von Aufgabe starten, bestätigen Sie vor dem Start, dass das Ziel erstellt werden kann und erreichbar ist und dass der Agent die benötigten Tools hat. Aus demselben Grund lesen Sie beim Überprüfen eines Batches zuerst die Transkripte der Läufe, die fehlgeschlagen sind oder nichts gefunden haben, bevor Sie die erfolgreichen lesen.

Führen Sie diese Überprüfungen manuell auf jedem Host durch. Die zweite Spalte beschreibt die Überprüfung für das Referenzdesign (Docker mit der Kata-Runtime und Firecracker). Passen Sie sie an Ihre eigene Runtime an.

Dieser Abschnitt beschreibt, wie die Referenzimplementierung die obige Anleitung erfüllt. Die Implementierung ist nicht enthalten. Lesen Sie es als ein Design, das Sie kopieren können.

Jeder Agent läuft als claude -p innerhalb seiner eigenen Micro-VM neben der Zielbinärdatei und Quelle. Die Micro-VM ist ein Kata Containers-Container, der von der Firecracker-Virtual-Machine-Monitor unterstützt wird und bei Docker als Runtime registriert ist. Die Tools Read, Write und Bash des Agenten sehen nur das Dateisystem und den Kernel dieses Gastes.

Die Verbindung zwischen einem Gast und dem Host ist absichtlich klein. Sie besteht aus KVM und den wenigen virtuellen Geräten, die Firecracker emuliert: Blockgeräte für die Festplatte des Containers, eine Netzwerkschnittstelle und einen vsock-Steuerkanal, den Kata zum Starten von Prozessen im Gast verwendet. Der Firecracker-Prozess selbst ist auf dem Host eingesperrt. Er läuft in einem "Jail", einem Chroot-Verzeichnis, das nur die Dateien dieser VM enthält, mit seinem eigenen Mount-Namespace, dem Netzwerk-Namespace des Containers und Firecrackers integriertem Seccomp-Filter. Er wird der Cgroup des Containers zugerechnet. Was Sie auf der Host-Seite vertrauen, ist KVM, Firecracker und Katas Runtime-Prozess (der Pro-Container-"Shim", mit dem Docker spricht und der als Root läuft).

Der Orchestrator bleibt auf dem vertrauenswürdigen Host. Er verwaltet den Container-Lebenszyklus, streamt Transkripte und verschiebt Dateien mit docker exec ein und aus, das Kata durch seinen Agenten im Gast bereitstellt. Der Launcher startet Agenten nur in dieser Sandbox. Bevor ein Agent startet, überprüft er, dass die Sandbox-Runtime registriert ist, dass /dev/kvm vorhanden ist und dass der Egress-Proxy aktiv ist, und weigert sich andernfalls zu laufen.

Was die Sandbox für jede Oberfläche ändert:

Wo jede Eigenschaft durchgesetzt wird: Hardware-Virtualisierung bietet die Kernel- und Dateisystem-Grenze. Die Read/Write/Bash-Operationen des Agenten laufen gegen den Gast-Kernel, und der Firecracker-Prozess dahinter ist auf dem Host eingesperrt und mit seccomp begrenzt. Die Egress-Richtlinie wird auf der Host-Seite der VM-Netzwerkschnittstelle durchgesetzt, durch eine Docker---internal-Bridge (keine Standardroute nach außen) und die beiden Proxies in diesem Netzwerk. Der Credential-Proxy leitet nur Modellaufrufe weiter und nichts anderes. Der Egress-Proxy lehnt jedes andere Ziel ab, da seine Allowlist leer ist, es sei denn, Sie fügen etwas hinzu. Der Datenverkehr verlässt den eigenen Netzwerk-Stack des Gastes; die Filterung erfolgt in den beiden Proxies.

Die Anmeldedaten für die Modell-API (Ihr API-Schlüssel, OAuth-Token, AWS- oder Google-Anmeldedaten) werden niemals in einem Agent-Container platziert. Der Orchestrator auf dem Host liest und validiert sie, und jeder Start startet einen kleinen zusätzlichen Container, den Credential-Proxy, um sie zu halten. Der Proxy ist mit dem internen Netzwerk der Agenten verbunden, und Agent-Container senden ihre Modellaufrufe daran: Ihre claude-CLI erhält die Adresse des Proxys als API-Basis-URL und einen festen Platzhalterwert, wo normalerweise der Schlüssel oder Token stehen würde. Dies folgt der Best Practice, die Modell-API nur über einen Proxy zu erreichen, wobei der API-Schlüssel von außerhalb der Sandbox injiziert wird. Im Referenzdesign ist der Proxy ein separater Container im Netzwerk der Agenten, kein Prozess auf dem eigenen localhost des Agenten. Für jede Anfrage führt der Proxy folgende Schritte durch:

Für einen kompromittierten Agent-Container bedeutet dies, dass es keinen Schlüssel, Token oder Anmeldedatei gibt, die gelesen, kopiert oder irgendwohin gesendet werden kann. Die Cloud-Metadatendienste sind auch vom Container aus nicht erreichbar. Was der Container immer noch tun kann, ist Modellaufrufe über den Proxy zu tätigen, auf Ihrem Konto, solange der Durchlauf läuft. Aus diesem Grund sollten Sie einen eng definierten Anmeldedaten für Agent-Durchläufe verwenden und ihn nach jedem Durchlauf rotieren, dessen Transkript unerwartet Verhalten zeigt. Der Proxy protokolliert eine Zeile pro Anfrage mit der Client-Adresse, Methode, Pfad, Status und Größe. Er protokolliert keine Header oder Texte. Speichern Sie dieses Protokoll, wenn der Durchlauf endet (siehe Abschnitt „Aufbewahrung

Alles, was der Agent an die Modell-API sendet, verlässt Ihr Netzwerk in Anfragetexten, die der Proxy nicht inspiziert oder protokolliert.

Was jede Seite pro Auth-Route hält:

Der Credential-Proxy-Container ist Teil der vertrauenswürdigen Seite des Setups. Er läuft unter einfachem runc statt der Sandbox-Laufzeit, als root mit allen Fähigkeiten gelöscht außer der einen, die er benötigt, um die eingebundenen Dateien zu lesen, und mit einem schreibgeschützten Dateisystem. Er lauscht nur auf seiner Adresse im internen Netzwerk der Agenten und verbindet sich direkt mit dem Provider statt über den Egress-Proxy. Der Orchestrator übergibt die Anmeldedaten über docker exec an den laufenden Proxy. Für die WIF-Token-Datei- und Profilrouten wird das Verzeichnis mit dem Token oder Profil schreibgeschützt in den Proxy eingebunden, der die Datei von dort liest. Die Anmeldedaten befinden sich nicht in der Umgebung oder Befehlszeile des Proxy-Containers, sodass docker inspect darauf die Einbindungen und nicht ein Geheimnis anzeigt.

Starten Sie einen Proxy pro Start und entfernen Sie ihn, wenn der Durchlauf endet oder unterbrochen wird. Überprüfen Sie auf Proxies, die von einem abgebrochenen Durchlauf zurückgelassen wurden, und entfernen Sie sie vor dem nächsten Start.

Der Credential-Proxy hat zwei Nebenwirkungen. Erstens erhält die CLI der Agenten eine nicht standardmäßige API-Adresse, sodass einige CLI-Funktionen, die nur auf die Standardadresse angewendet werden, in Agent-Containern ausgeschaltet sind. Auch die Telemetrie und Update-Prüfungen sind ausgeschaltet, da sie ohnehin keine Route nach außen hätten. Zweitens ist auf Vertex der Pfadfilter des Proxys die Hauptkontrolle, die verhindert, dass ein Agent-Container den Rest der Vertex-AI-API verwendet (siehe Egress-Allowlist). Eine Überprüfung des IAM-Umfangs des Schlüssels beim Start ist eine zweite Ebene.

Die Allowlist des Egress-Proxys ist standardmäßig leer. Agent-Container erreichen die Modell-API nur über den Credential-Proxy (siehe Der Credential-Proxy). Jeder Start startet diesen Proxy für den Provider, den Ihre Anmeldedaten auswählen, sodass nichts Anbieter-Spezifisches im Sandbox-Setup gespeichert wird. Jedes andere Ziel, das ein Agent über den Egress-Proxy anfordert, einschließlich des Modell-API-Hosts selbst, erhält eine 403 und eine Ablehnungszeile in seinem Protokoll. Die Regionswerte, die die Bedrock- und Vertex-Endpunkte auswählen (AWS_REGION, CLOUD_ML_REGION), werden vor der Verwendung gegen ein striktes Muster überprüft, sodass ein fehlerhafter Wert die Anmeldedaten nicht an einen anderen Host senden kann.

Vertex hat eine Einschränkung, die Sie beachten sollten. …aiplatform.googleapis.com bedient die gesamte Vertex-AI-API, sodass ein Anmeldedaten, das zum Erstellen benutzerdefinierter Jobs berechtigt ist, einen beliebigen Container mit vollständigem Internet-Egress in Ihrem Projekt ausführen könnte. Verwenden Sie zwei Kontrollen dagegen. Lassen Sie den Credential-Proxy nur Publisher-Modellaufrufe auf Ihrem konfigurierten Projekt weiterleiten (…/publishers/anthropic/models/…:rawPredict, :streamRawPredict und :countTokens) und lehnen Sie jeden anderen Pfad ab. Und überprüfen Sie den IAM-Umfang des Schlüssels beim Start und schließen Sie fehlgeschlagen: lehnen Sie gcloud-Benutzer-ADC ab, überprüfen Sie einen Service-Account-Schlüssel mit testIamPermissions und lehnen Sie ihn ab, wenn er eine Berechtigung zur Workload-Erstellung hält. Gewähren Sie dem Konto eine benutzerdefinierte Rolle, die nur aiplatform.endpoints.predict hält. Der Metadaten-Server, Googles STS und die IAM-Credentials-Endpunkte sollten von Agent-Containern aus nicht erreichbar sein.

Wenn Agenten zusätzliche Hosts erreichen müssen, z. B. einen Paket-Mirror oder ein Ziel im Umfang, fügen Sie sie als Host:Port-Einträge zur Allowlist des Egress-Proxys hinzu. Fügen Sie nur hinzu, was das Engagement benötigt (siehe Umfang und Aufsicht).

Fügen Sie den Model-API-Host nicht zu dieser Liste hinzu. Agents benötigen ihn nicht, da ihre Modellaufrufe über den Credential-Proxy laufen. Das Hinzufügen gibt Agent-Containern eine direkte Route zur API, und der Rest des Designs, einschließlich dessen, was dem Permission Classifier mitgeteilt wird, geht davon aus, dass sie keine haben.

Das Ändern der Allowlist erfordert einen Neustart des Egress-Proxy, was alle aktiven Agent-Verbindungen unterbricht. Führen Sie dies zwischen Batches durch, nicht während eines, und bestätigen Sie anschließend, welche Liste der Proxy geladen hat.

Leiten Sie den Provider-Endpunkt von Ihrer Credential-Konfiguration ab und ignorieren Sie eine Basis-URL-Variable wie ANTHROPIC_BASE_URL, die auf dem Host gesetzt ist: Der Credential-Proxy sollte immer zum Endpunkt weiterleiten, den die Credentials auswählen.

Dieser Abschnitt sammelt, was aus dem Betrieb von Agents unter Kata mit Firecracker in der Referenzimplementierung gelernt wurde. Es ist keine Anleitung zur Installation.

Das Referenzdesign benötigt einen physischen Linux-Rechner oder eine VM, die selbst VMs ausführen kann:

Seine Sandbox benötigt KVM auf einem Linux-Host. Docker auf einem Mac läuft in einer gemeinsamen Linux-VM, die das Home-Verzeichnis des Benutzers bereitstellt und den Docker-Daemon hält, sodass es keine Hardware-Isolation pro Agent bieten kann. Wenn Sie auf einem Mac arbeiten, führen Sie die Agents auf einem Linux-Host mit KVM aus (Bare Metal oder eine Cloud-VM mit aktivierter verschachtelter Virtualisierung) und steuern Sie sie über SSH. Wenn Sie Ihre eigene Sandbox auf macOS oder Windows erstellen, siehe die Hypervisoren, die im Abschnitt Allgemeine Richtlinien oben genannt werden.

Images und Container, die im vorherigen Docker-Speicher erstellt wurden, werden für Docker nach dem Wechsel zum devmapper-Snapshotter unsichtbar. Sie bleiben auf der Festplatte. Um sie erneut anzuzeigen, setzen Sie beide Speichereinstellungen in daemon.json (storage-driver und features.containerd-snapshotter) auf das zurück, was sie waren, und starten Sie Docker neu.

Fixieren Sie die Kata-Version und überprüfen Sie ihren Digest, bevor Sie sie installieren. Das Referenzdesign beginnt mit Katas Firecracker-Profil und fixiert diese Einstellungen in /etc/kata-containers/configuration.toml:

Die kernel-, image- und kernel_params-Werte, die mit der Kata-Version geliefert werden, werden unverändert beibehalten.

Jede VM startet von denselben zwei Dateien, Kata bindet sie in jeden Jail ein, und der Jailer wird als Root gestartet, sodass normale Dateiberechtigungen einen kompromittierten Firecracker-Prozess nicht daran hindern würden, das Image umzuschreiben, von dem jede spätere VM startet. Setzen Sie das Immutable-Flag auf beiden (chattr +i). Das Löschen dieses Flags erfordert einen Systemaufruf, den Firecrackers Seccomp-Filter nicht zulässt, was verhindert, dass selbst Root im Jail dies tut. Löschen Sie das Flag selbst, bevor Sie eine neue Kata-Version installieren. Verwenden Sie auf einem Dateisystem ohne chattr-Unterstützung stattdessen ein schreibgeschütztes Bind-Mount.

Jede Agent-VM wird einmal beim Start dimensioniert: default_memory plus das --memory des Containers. Mit einer 4096-MiB-Baseline und einem 4g-Container-Limit ist ein Agent eine 8-GiB-VM. Der Host weist der VM den Speicher zu, wenn der Gast ihn nutzt, nicht alle beim Start, aber planen Sie für den vollen Betrag pro gleichzeitigem Agent: Zehn Agenten parallel können sich 80 GiB nähern. Ob das --memory-Limit des Containers auch die gesamte VM begrenzt, hängt davon ab, wie die Cgroups des Hosts angeordnet sind. Überprüfen Sie, welche dieser Optionen auf Ihrem Host zutrifft:

Wir haben dieses Verhalten nicht auf jeder Art von Host bestätigt. Dimensionieren Sie den Host in jedem Fall nach VM-Größe.

Jede VM erhält default_vcpus. Firecracker kann einer laufenden VM keine CPUs hinzufügen, daher erhöhen Sie den Wert vor dem Start für Build-intensive Ziele; das Maximum beträgt 32 pro VM.

Jedes Image und jeder Container erhält eine virtuelle Festplatte aus einem Device-Mapper-Thin-Pool, der den Image-Store unterstützt. Wenn der Pool voll wird, schlagen Schreibvorgänge in Containern mit E/A- oder Speicherplatzfehlern fehl. Wenn das Dateisystem, das den Pool enthält, zuerst voll wird, wird der Pool schreibgeschützt und jeder Container darauf schlägt fehl. Geben Sie Speicherplatz mit docker rmi und docker system prune frei (freigegebene Blöcke kehren zum Pool zurück). sudo dmsetup status <pool> zeigt die Nutzung. Für einen langlebigen Host ist ein LVM-Thin-Pool auf einer dedizierten Festplatte das bessere Layout.

Jeder Agent-Start startet einen Gast-Kernel. Das dauert auf Bare Metal deutlich unter einer Sekunde und unter verschachtelter Virtualisierung einige Sekunden, was klein im Vergleich zu Agent-Laufzeiten ist.

Nach dem Einrichten einer neuen Maschine zeigt diese Sequenz, dass die Sandbox end-to-end funktioniert. Die Schritte 3 und 4 führen echte Model-Aufrufe durch.

Das Ausführen von Agenten unter Kata mit Firecracker unterscheidet sich vom Ausführen einfacher Container auf diese Weise.

Firecracker hat keine Host-Dateisystem-Freigabe, daher kopiert Kata eine Bind-Mount-Datei oder ein Verzeichnis beim Start des Containers in den Gast, und spätere Änderungen auf dem Host werden nicht angezeigt. Das ist in Ordnung für Eingaben, die sich während eines Laufs nicht ändern, wie z. B. Zielquelle, und diese können schreibgeschützte Mounts bleiben. Keine Anmeldedaten-Datei wird bereitgestellt oder gestreamt, da Agent-Container keine enthalten (siehe Der Anmeldedaten-Proxy). Eine Datei, die sich während eines Laufs ändert, muss vom Orchestrator in den Container geschrieben werden, über docker exec, und aktuell gehalten werden. Die In-Container-Kopien sind gewöhnliche Dateien, die ein Agent bearbeiten könnte, daher lesen Sie die Originale auf dem Host vom Orchestrator und beurteilen Sie Erkenntnisse aus einer Kopie, die der getestete Agent nicht erreichen kann.

Die Netzwerkschnittstellen einer MicroVM müssen vorhanden sein, wenn die VM startet; Firecracker kann später keine hinzufügen. Docker verbindet jedoch die Netzwerk eines Containers erst, nachdem die Runtime den Container erstellt hat. Das Referenzdesign umgeht dies. Es startet zunächst einen kleinen Idle-Container, der an das richtige Netzwerk angebunden ist und nur sleep ausführt, und startet dann den Agent im Netzwerk-Namespace dieses Containers (--network container:<name>). Kata findet die Schnittstellen dort beim Start und bindet sie an die VM. Ein Begleiter bedient genau eine VM, da Kata die Host-seitigen Netzwerk-Geräte der VM darin hinterlässt, daher erstellen und entfernen Sie das Paar zusammen und verwenden Sie einen Begleiter nicht erneut. Einer kostet einen Idle-Prozess von ungefähr 12 MB.

docker rm -f <agent-container> reicht aus. Der Orchestrator sollte den toten Container erkennen, den Lauf als fehlgeschlagen markieren und den Begleit-Container entfernen, wenn er den Lauf abbaut.

Dockers eingebettetes DNS läuft im Host-seitigen Netzwerk-Namespace und ist von innen aus einem Gast nicht erreichbar. Übergeben Sie die Proxys daher als IP-Adressen an Agenten und weisen Sie vernetzten Zielen eine statische IP zu.

docker exec in einen Agent-Container verhält sich wie gewohnt; Katas Agent im Gast führt den Befehl aus. docker cp in oder aus einem Agent-Container funktioniert nicht, da sich die Dateien des Containers auf einer virtuellen Festplatte im Gast befinden. Verwenden Sie docker exec <container> cat <path> und ähnliches.

Kata startet den Jailer mit uid 0, daher wird der Firecracker-Prozess durch sein chroot, seine Namespaces, seinen seccomp-Filter und seine cgroup eingeschränkt, nicht durch eine unprivilegierte Benutzer-ID. Die beiden Dateien, die jede VM gemeinsam nutzt – der Gast-Kernel und das Image – werden stattdessen durch das Immutable-Flag geschützt (siehe Kata-Einstellungen).

Kata führt Firecracker über seine ältere Go-Runtime aus. Kata 4.0 machte eine neuere Rust-Runtime zur Standardeinstellung für seine anderen Hypervisoren und veraltete die Go-Runtime. Upstream gibt an, dass die Go-Runtime weiterhin kritische Fehlerbehebungen und CVE-Fixes erhält und dass sie möglicherweise nicht vor Kata 5.0 entfernt wird. Die Rust-Runtime listet Firecracker nicht unter ihren Hypervisoren auf, und Upstream testet ihre Docker-Integration hauptsächlich mit QEMU. Planen Sie eine Migration. Wenn Sie die Kata-Version ändern, wiederholen Sie Validierung eines neuen Hosts. Kata kann auch Cloud Hypervisor statt Firecracker verwenden; die Referenzimplementierung hat diese Konfiguration nicht getestet oder gehärtet.

Katas Runtime-, Firecracker- und Guest-Agent-Meldungen gehen ins Journal: journalctl -t kata. containerd- und Docker-Probleme finden sich in journalctl -u containerd und journalctl -u docker.