E2B

Run sandbox tools in E2B while OpenAI runs the agent and maintains session state.

Choose a provisioning mode:

• Application-managed: Your application creates and connects the E2B sandbox directly.
• Webhook-managed: Deploy a handler that starts or reconnects sandboxes from OpenAI webhooks.

See Sandbox lifecycle to compare the two modes.

Before you begin

Set E2B_API_KEY, OPENAI_API_KEY, and a separate restricted OPENAI_EXECUTOR_API_KEY. Keep the application key outside the worker sandbox. The executor key must match the session owner’s organization, project, and user or service account. See executor authentication.

Webhook-managed

Implement a controller that verifies OpenAI webhooks and provisions a separate E2B worker for each session. Follow Deploy and connect a handler for credentials, endpoint registration, and signature verification.

Persist the session-to-sandbox mapping. On a connection request, resume a paused worker or replace a deleted one. Pausing preserves its files; replacement does not. Set running timeouts for the controller and workers, and remove the OpenAI webhook when you stop using the controller.

Application-managed

Use the E2B SDK or API from your application to manage the sandbox:

1. Create a self-hosted session and save its environment ID.
2. Create an isolated E2B sandbox with the session’s working directory and install the Codex CLI inside it.
3. Start the executor in the sandbox using the environment ID and restricted executor key.
4. Use Run and continue sessions to send input and check the turn’s outcome.
5. Delete the session and stop the E2B sandbox when finished.

Configure the sandbox lifetime separately from the timeout for the executor command. A command with no timeout does not keep an expired sandbox running.

References

• Read E2B documentation
• Read E2B Python SDK
• Read E2B TypeScript SDK