Run an Agents API session with a Modal sandbox.
See Self-hosted sandboxes for executor setup and connection requirements.
Choose a provisioning mode:
- Application-managed: Follow this guide to start and stop sandboxes from your application.
- Webhook-managed: Deploy a handler that starts or reconnects sandboxes from OpenAI webhooks.
See Sandbox lifecycle to compare the two modes.
Before you begin
You need an OpenAI project API key, a Modal token ID and secret, and the Codex CLI package.
Set OPENAI_API_KEY for application requests and a separate restricted OPENAI_EXECUTOR_API_KEY for sandbox registration. Grant the application key api.agents.read and api.agents.write for session operations, plus api.responses.write for model inference. Add api.vaults.read and api.vaults.write if your application manages vaults. Create the executor’s environment key and use the same organization, project, and user or service account for both keys. Only the restricted executor key enters the sandbox.
1. Set up the Modal environment
Create a self-hosted session and save its environment ID. Use the Modal SDK or API to create an isolated sandbox with the configured working directory. Install the Codex CLI in the sandbox, then start its executor with that environment ID and the restricted executor key.
2. Run the session
Use the HTTP examples in Run and continue sessions to send input and stream the result after the Modal executor connects. When finished, delete the session and stop the provider sandbox separately.