Claude Agent SDK Sandbox: Jede Aufgabe im eigenen Arbeitsbereich ausführen

Eine Sandbox für das Claude Agent SDK ist die Umgebung, in der der Agentenprozess des SDK, seine Tools und Arbeitsdateien ausgeführt werden. Das SDK startet einen Claude CLI-Unterprozess. Wenn Sie diesem Prozess eine separate VM oder einen Container zuweisen, können Sie festlegen, auf welche Dateien und Anmeldeinformationen er zugreifen kann und was nach Ende der Aufgabe passiert. Ein Arbeitsverzeichnis allein schafft diese Grenze nicht. Hosting-Leitfaden von Anthropic

Verwenden Sie für unabhängige Aufgaben jeweils einen eigenen Arbeitsbereich. Behalten Sie bei einer Sitzung über mehrere Anfragen hinweg den Arbeitsbereich bei oder speichern Sie den Zustand, der zum Fortsetzen nötig ist. Verwalten Sie Authentifizierung, Aufgabenzuordnung und Zeitplanung in einem Koordinator außerhalb der Maschine des Agenten.

Wir entwickeln Lizard. Dieser Leitfaden nutzt Lizard Sandboxes für ein kleines Einrichtungsbeispiel und vergleicht die Hosting-Optionen. Wir haben die APIs und Befehle am 4. November 2026 geprüft. Das neue SDK-Beispiel haben wir anhand der Dokumentation überprüft; wir haben es nicht in einer Cloud-Sandbox mit Anthropic ausgeführt.

Was muss der Host bereitstellen?

Das Agent SDK benötigt eine Laufzeitumgebung, einen CLI-Unterprozess, ein Arbeitsverzeichnis und Zugriff auf den Modelldienst. Der Unterprozess kann auch Tools starten, die mehr Arbeitsspeicher, CPU und Festplattenspeicher benötigen als das SDK selbst. Dimensionieren Sie den Arbeitsbereich passend zur Aufgabe: Einige Dateien zu lesen stellt andere Anforderungen als ein Repository zu bauen oder einen Browser zu steuern.

Lokale Verzeichnisse trennen den Anwendungszustand, doch Prozesse mit denselben Zugriffsrechten im Betriebssystem können weiterhin auf andere Verzeichnisse zugreifen. Verwenden Sie für voneinander unabhängige Benutzer eine Grenze, die diesem Risiko entspricht. Anthropics Leitfaden zur sicheren Bereitstellung behandelt Isolierung und Anmeldeinformationen.

Hosting-Umgebung wählen

Lizard Sandboxes bietet Firecracker-MicroVMs mit eigenen Kerneln, fertigen Vorlagen, Befehlsausführung und Dateiübertragung. Sie eignen sich für CPU-Aufgaben, die in die festen Maschinengrößen passen. Lizard bietet keine GPU-Instanzen für Sandboxes und keine beliebigen Sandbox-Vorlagen auf Dockerfile-Basis. Lizard Sandboxes

E2B bietet Linux-Sandboxes, Vorlagen und APIs zur Codeausführung. Daytona bietet Arbeitsbereichs-Tools und mehrere Laufzeitklassen. Modal unterstützt elastische CPU-Ressourcen und GPU-Workflows mit laufzeitspezifischen Einschränkungen. Eine Docker- oder Kubernetes-Bereitstellung gibt Ihnen die Kontrolle über Ihre eigene Infrastruktur, während Sie sich um Kapazität, Isolierung und Bereinigung kümmern. E2B, Daytona, Modal

Das SDK kann auf einem Host mit der nötigen Laufzeitumgebung und Unterstützung für Unterprozesse laufen; es setzt keinen bestimmten Sandbox-Anbieter voraus. Prüfen Sie Abhängigkeiten, Netzwerkzugriff, Verhalten beim Herunterfahren und Arbeitsspeicherbedarf unter Ihrer eigenen Arbeitslast.

Mit einer kleinen SDK-Aufgabe mit reinem Lesezugriff beginnen

Dieses Beispiel liest eine lokale Projektdatei und bittet Claude um eine Zusammenfassung. Es stellt dem Agenten nur die Tools Read, Glob und Grep bereit. Es benötigt weder uneingeschränkte Bash-Ausführung noch eine Umgehung der Berechtigungsprüfung.

Sie benötigen ein Lizard-Projekt, eine angemeldete Lizard CLI und einen Anthropic-API-Schlüssel für Modellaufrufe. Lizard-Rechenleistung und Anthropic-Nutzung werden getrennt abgerechnet. Installieren Sie die CLI anhand der aktuellen Anleitung.

1. Einen Arbeitsbereich der Größe Small erstellen

Ersetzen Sie den Projektplatzhalter und kopieren Sie dann die zurückgegebene Sandbox-ID nach SB:

lizard sandbox create --project YOUR_PROJECT_ID \
  --template claude --size small --timeout 3600000 --json
SB=YOUR_SANDBOX_ID
lizard sandbox exec "$SB" -- mkdir -p /workspace/agent

Die explizite Lebensdauer beträgt eine Stunde. Der CLI-Standardwert beträgt fünf Minuten, und das Ausführen von Befehlen setzt diese Frist nicht zurück. Legen Sie eine passende Frist für die Aufgabe fest und speichern Sie die Ergebnisse vor deren Ablauf. Sandbox-CLI

2. Den SDK-Runner lokal speichern

Erstellen Sie summarize.mjs mit diesem Code:

import { query } from '@anthropic-ai/claude-agent-sdk';

if (!process.env.ANTHROPIC_API_KEY) {
  throw new Error('Set ANTHROPIC_API_KEY inside the task environment');
}

let completed = false;
for await (const message of query({
  prompt: 'Read README.md and summarize the project in two sentences.',
  options: {
    cwd: '/workspace/agent',
    settingSources: [],
    tools: ['Read', 'Glob', 'Grep'],
    allowedTools: ['Read', 'Glob', 'Grep'],
    permissionMode: 'dontAsk',
    maxTurns: 6,
  },
})) {
  if (message.type !== 'result') continue;
  if (message.subtype !== 'success' || message.is_error) {
    throw new Error(`Agent failed: ${message.subtype}`);
  }
  completed = true;
  console.log(message.result);
}
if (!completed) throw new Error('Agent ended without a successful result');

tools wählt die verfügbaren integrierten Tools aus. allowedTools genehmigt Aufrufe vorab; allein bildet es keine vollständige Tool-Allowlist. dontAsk lehnt Anfragen ohne Berechtigung ab. Das niedrige Rundenlimit begrenzt die Agentenschleife dieses Beispiels; es begrenzt nicht die gesamten Cloud-Ausgaben. Agent SDK-Referenz

Erstellen Sie eine kleine README.md neben dem Skript und laden Sie dann beide Dateien hoch:

lizard sandbox files put "$SB" ./summarize.mjs /workspace/agent/summarize.mjs
lizard sandbox files put "$SB" ./README.md /workspace/agent/README.md
lizard sandbox shell "$SB"

3. Im Arbeitsbereich installieren und ausführen

In der Bash-Shell der Sandbox:

cd /workspace/agent
npm init -y
npm install --save-exact @anthropic-ai/claude-agent-sdk
read -rsp 'Anthropic API key: ' ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY
node summarize.mjs
unset ANTHROPIC_API_KEY

Das erwartete Ergebnis ist eine kurze Zusammenfassung auf stdout und ein Exit-Status von null. Fehlende Anmeldeinformationen, ein verweigerter Vorgang oder ein ausgeschöpftes Rundenlimit sollten zum Fehlschlagen des Laufs führen. Behalten Sie die erzeugte Lockdatei bei und verwenden Sie npm ci, wenn Sie aus dem Beispiel eine wiederholbare Umgebung machen.

Die Eingabeaufforderung verhindert, dass der Schlüssel im Shell-Verlauf landet. Während die Aufgabe läuft, befindet sich der Schlüssel weiterhin in der Umgebung des Agenten. Erwägen Sie für einen Dienst, der nicht vertrauenswürdige Aufgaben ausführt, einen ausgehenden Proxy, der Anmeldeinformationen außerhalb der Sandbox einfügt. SDK-Authentifizierung und Hosting

4. Benötigte Daten exportieren, dann pausieren

Verlassen Sie die Sandbox-Shell und rufen Sie alle benötigten Ausgabedateien mit lizard sandbox files get ab. Sobald Sie das Ergebnis gespeichert haben:

lizard sandbox pause "$SB"

Bestätigen Sie, dass der Endstatus paused lautet. Eine erfolgreiche Pause beendet die Rechenkosten und erhält den Zustand des Arbeitsbereichs; Speicher für Persistent Volumes wird separat abgerechnet. Die lokale Festplatte dieses Beispiels wird nicht allein dadurch zu dauerhaftem Speicher, dass ihr Pfad mit /workspace beginnt. Persistenz, Persistent Volumes

Den Runner für den Produktionsbetrieb ergänzen

Legen Sie für jede Anfrage einen Aufgabeneintrag an, bevor Sie einen Agenten starten. Speichern Sie Besitzer, Sandbox-ID, Status, Frist und Ausgabeort. Übertragen Sie den Fortschritt fortlaufend über den Koordinator und bewahren Sie das Endergebnis unabhängig von der Client-Verbindung auf.

Behandeln Sie Abbruch und Bereinigung in getrennten Abläufen. Ein Verbindungsabbruch des Clients muss nützliche Arbeit nicht beenden; eine abgebrochene Aufgabe sollte keine unbemerkte Maschine weiterlaufen lassen. Wiederholen Sie die Bereinigung nach vorübergehenden Fehlern und gleichen Sie Aufgabeneinträge mit den tatsächlichen Sandbox-Zuständen ab.

Speichern Sie für Sitzungen die Sitzungs-ID und den benötigten Protokoll- und Dateizustand. Eine Datenbankzeile mit nur der ID kann fehlende Dateien des Arbeitsbereichs nicht wiederherstellen. Anthropic dokumentiert die Sitzungsspeicherung getrennt von den Artefakten des Arbeitsverzeichnisses. Sitzungen, Hosting-Zustand

Halten Sie wiederverwendbare Vorlagenzustände frei von Benutzer-Anmeldeinformationen und privaten Aufgabendateien. Stellen Sie diesen sauberen Zustand für jede unabhängige Aufgabe wieder her. Machen Sie die pausierte Maschine eines Benutzers nicht ohne eine nachweislich wirksame Zurücksetzung zum Arbeitsbereich eines anderen Benutzers.

Was kostet der Arbeitsbereich?

Lizard Small kostet $0.0162 pro Betriebsstunde. Insgesamt einhundert Betriebsstunden verbrauchen $1.62 an Rechenleistung; für ein neues Pro-Konto gilt weiterhin ein monatlicher Mindestbetrag von $19 mit $19 an enthaltener Nutzung. Modellaufrufe, Persistent Volumes und andere Ressourcen benötigen ein eigenes Budget. Lizard-Preise

Pro unterstützt 20 Small-Sandboxes gleichzeitig und 400 neue Starts pro Tag, zusätzlich gelten Startlimits pro Minute und Stunde. Pro 5x kostet $99 mit $99 an Nutzung und unterstützt bis zu 110 Small-Sandboxes; Pro 20x kostet $499 mit $499 an Nutzung und unterstützt bis zu 600. Mehr gleichzeitige Aufgaben bedeuten nicht, dass jede Aufgabe gleich schnell fertig wird. Aktuelle Limits

Messen Sie die gesamte Laufzeit, einschließlich Paketinstallation, Wartezeiten auf das Modell und Ausgabeübertragung. Wenn Sie einen Arbeitsbereich zwischen Anfragen pausieren, muss der Koordinator außerhalb davon bleiben: Ein pausierter Prozess kann die Anfrage, die ihn selbst aufweckt, nicht empfangen.

Ist das Arbeitsverzeichnis des Claude Agent SDK eine Sandbox? Nein. cwd legt fest, wo der Prozess arbeitet. Verwenden Sie Betriebssystemsteuerungen oder einen separaten Container oder eine VM, um den Zugriff über dieses Verzeichnis hinaus festzulegen.

Kann ich mit Claude Code beginnen, statt einen SDK-Dienst zu schreiben? Ja. Für eine einzelne Programmieraufgabe zeigt der Claude Code-Sandbox-Leitfaden den kürzeren CLI-Workflow. Verwenden Sie das SDK, wenn Ihre Anwendung Agentennachrichten, Tool-Richtlinien und Sitzungsverhalten im Code verwalten muss.