Modal
On this page
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending
.mdto the page URL.
See the application-managed and webhook-managed examples in the OpenAI Cookbook.
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.
Use OPENAI_API_KEY for application requests. Set OPENAI_EXECUTOR_API_KEY to an environment key, and pass only that key into the sandbox as CODEX_API_KEY.
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 environment 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.
