Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Selbst gehostete Sandboxen

Verbinde deine Rechenressourcen und Dateien mit einer Agentensitzung.

Binde deine eigene Umgebung an, wenn du mehr Kontrolle über die Arbeitsumgebung des Agenten möchtest oder Rechenressourcen nutzen willst, denen du vertraust. Als Umgebung kannst du einen Laptop, einen Container oder eine Remote-Sandbox verwenden. Wenn OpenAI die Umgebung bereitstellen soll, verwende eine von OpenAI gehostete Sandbox.

So funktioniert die Verbindung

OpenAI betreibt den Agenten-Harness. In deiner Umgebung führst du codex exec-server als Executor aus. Auf Anforderung des Harness führt der Executor Shell-Befehle aus, liest und schreibt Dateien und nutzt lokale MCP-Server.

Der Executor registriert sich mit einer Umgebungs-ID und einem API-Schlüssel mit eingeschränkten Berechtigungen bei der API. Anschließend stellt er eine WebSocket-Verbindung her, über die er Befehle empfängt und Ergebnisse zurücksendet. Alle Verbindungen sind ausgehend. Wenn die Verbindung abbricht, stellt der Executor sie wieder her.

Der Sandbox-Executor stellt eine ausgehende Verbindung zur Agents API her, empfängt Befehle und sendet Ergebnisse zurück. Der Umgebungsschlüssel und die Umgebungs-ID befinden sich in der Sandbox.

Umgebung vorbereiten

Stelle die Dateien und Abhängigkeiten bereit, die dein Agent benötigt. Verwende für jede Person oder jeden Workload eine separate Umgebung. Agenten, die sich eine Umgebung teilen, können auf dieselben Dateien, Zugangsdaten und anderen Ressourcen zugreifen.

Um die automatische Überprüfung mit review: "auto_review" zu aktivieren, führe den Standard-Executor in einem Container aus, der Sandboxing unterstützt und Codex das Erstellen einer Sandbox erlaubt. Die automatische Überprüfung verwendet ein Berechtigungsprofil auf Basis von workspace-write mit eingeschränktem Netzwerkzugriff. Prüfe vor dem Aktivieren die Voraussetzungen für die automatische Überprüfung.

Erstelle das Arbeitsverzeichnis und installiere die Codex CLI in der Umgebung. In diesem Beispiel ist /workspace das Arbeitsverzeichnis.

mkdir -p /workspace
npm install -g @openai/codex@alpha

Netzwerkzugriff

Erlaube ausgehende Verbindungen zu diesen Hosts:

  • https://api.openai.com für die Registrierung der Umgebung.
  • wss://codex-cloud-environments.chatgpt.com für Befehle und Ergebnisse.

Authentifizierung

Verwende OPENAI_API_KEY für Anfragen deiner Anwendung. Erteile dem Schlüssel die Berechtigungen api.agents.read und api.agents.write für Sitzungsoperationen sowie api.responses.write für die Modellinferenz. Füge api.vaults.read und api.vaults.write hinzu, wenn deine Anwendung Vaults verwaltet.

Erstelle im Plattform-Dashboard auf dem Tab „Agenten“ einen separaten Umgebungsschlüssel. Er muss derselben Organisation, demselben Projekt und demselben Benutzer- oder Dienstkonto zugeordnet sein wie die Sitzung. Setze alle anderen Berechtigungen auf None.

Setze OPENAI_EXECUTOR_API_KEY in deiner Anwendung oder deinem Bereitstellungsdienst auf diesen Umgebungsschlüssel. Übergib den Wert als CODEX_API_KEY an die Sandbox. codex exec-server liest den Schlüssel aus dieser Variablen. Bewahre den OPENAI_API_KEY deiner Anwendung außerhalb der Sandbox auf.

Vom Agenten generierter Code kann den Umgebungsschlüssel lesen. Der Schlüssel erlaubt jedoch nur das Verbinden von Umgebungen. Er kann keine andere API-Aktion autorisieren. Halte ihn aus Quellcode, Container-Images und Protokollen heraus. Tausche ihn bei Bedarf aus oder widerrufe ihn.

Sitzung erstellen

Führe dieses Beispiel in deiner Anwendung außerhalb der Umgebung aus. Wenn du bereits eine selbst gehostete Sitzung hast, verwende sie weiter.

Sitzung mit deiner eigenen Umgebung erstellen
import OpenAI from "openai";
const client = new OpenAI();

const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions:
      "You are a helpful coding assistant. Write clean code and verify that it works.",
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace",
  },
});

console.log(session);

Speichere session.id zusammen mit dem Gesprächszustand deiner Anwendung. Übergib session.environment.id und session.environment.remote_url an den Executor. Verwende die Remote-URL unverändert, auch beim Wiederherstellen der Verbindung. Wie du einen gespeicherten Agenten verwendest, erfährst du im Abschnitt Agenten konfigurieren.

Du kannst das Image deiner Umgebung sowie workspace_directory und capability_directories für mehrere Sitzungen verwenden. Jede Sitzung hat eine eigene Umgebungs-ID und benötigt einen eigenen Executor. Die Umgebungsvorlagen der API gelten nur für von OpenAI gehostete Umgebungen.

Executor starten

Öffne in deiner Anwendung den Ereignisstream der Sitzung, um Verbindungsereignisse zu empfangen. Führe dann den folgenden Befehl in der Umgebung aus. Der Umgebungsschlüssel muss dabei wie oben beschrieben als CODEX_API_KEY gesetzt sein. Ersetze die Platzhalter durch die Umgebungswerte, die die API zurückgegeben hat.

codex exec-server \
  --remote "<session.environment.remote_url>" \
  --environment-id "<session.environment.id>"

Lass den Executor laufen, während der Agent arbeitet.

Aufgaben senden und die Verbindung überwachen

Sende eine Eingabe aus deiner Anwendung und halte dabei den Ereignisstream offen. Der Agent benötigt sowohl eine verbundene Umgebung als auch eine Benutzereingabe, um mit der Arbeit zu beginnen.

Der Stream meldet folgende Verbindungszustände:

  • agent.session.environment.pending: Die Sitzung wartet darauf, dass der Executor eine Verbindung herstellt.
  • agent.session.environment.connected: Die Umgebung ist bereit.
  • agent.session.environment.failed: Die Verbindung ist fehlgeschlagen. Prüfe die Fehlermeldung der Umgebung und die Protokolle des Executors.

Verfolge den Stream weiter, um zu sehen, wie der aktuelle Durchlauf endet und welche Ausgabe er liefert. Im Abschnitt Lebenszyklus der Umgebung erfährst du, wie du den Start, den erneuten Verbindungsaufbau und das Herunterfahren über deine Anwendung oder über Webhooks steuerst.

Sandbox-Anbieter

Wähle einen Sandbox-Anbieter, um Code auszuführen und mit Dateien zu arbeiten. Im Abschnitt Lebenszyklus der Sandbox findest du einen Vergleich der Bereitstellung über die Anwendung und über Webhooks.

Anbieter Anleitung
AWS Lambda MicroVMs AWS-Setup
Blaxel Blaxel-Setup
Cloudflare Cloudflare-Setup
Databricks Sandbox Databricks-Setup
Daytona Daytona-Setup
DigitalOcean DigitalOcean-Setup
E2B E2B-Setup
Modal Modal-Setup
Oracle Cloud Infrastructure (OCI) OCI-Setup
Vercel Vercel-Setup

Für die Bereitstellung über Webhooks implementierst du einen Handler. Nutze dazu die Anleitung zum Lebenszyklus der Sandbox und das SDK oder die API deines Anbieters. Lege ausdrücklich fest, wer für die Bereitstellung verantwortlich ist und nach welchen Regeln Ressourcen freigegeben werden.