All guides
OpenAI

Blaxel

Checked 09/15/2026View original
English original
On this page

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to 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 Blaxel API key and workspace, and the Codex CLI package.

Set BL_API_KEY and BL_WORKSPACE, and 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.

Choose the sandbox region in your provisioning code. Use us-was-1 if you need the Agent Drive persistence option below.

1. Set up the Blaxel environment

Create a self-hosted session and save its environment ID. Use the Blaxel 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.

The Blaxel Node image uses Alpine Linux, so install ripgrep with apk. Pass the environment key as CODEX_API_KEY only to the executor process. Set keep_alive=True to prevent the sandbox from scaling to zero while the executor runs. Bounded setup, executor, and sandbox timeouts prevent abandoned resources from running indefinitely.

For regular use, build a Blaxel image with Codex and ripgrep already installed so the sandbox can connect sooner.

2. Run the session

Use the HTTP examples in Run and continue sessions to send input and stream the result after the Blaxel executor connects. When finished, delete the session and stop the provider sandbox separately.

Start the sandbox before submitting input. The turn waits for the environment to connect, and the session reports the connection through agent.session.environment.connected on the event stream.

Use agent.session.turn.completed to identify a successful turn. A failed or cancelled turn can also be followed by agent.session.idle, so do not treat an idle session as proof that the turn succeeded.

Optional: Persist files between sessions

Use Blaxel Agent Drive to preserve files across sandboxes and sessions. Mount the same drive in each sandbox to share files; Agent Drive requires the us-was-1 region and does not transfer conversation history or session state.

References