For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Suggested

Agents API

Agents SDK

ChatKit

API Dashboard
Try ChatGPT

Blaxel

Run an Agents API session in a Blaxel sandbox.

Run an Agents API session with a Blaxel 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 Blaxel API key and workspace, and the Codex CLI package.

Set OPENAI_API_KEY, a separate restricted OPENAI_EXECUTOR_API_KEY, BL_API_KEY, and BL_WORKSPACE in your environment. 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. 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 restricted executor key.

The Blaxel Node image uses Alpine Linux, so install ripgrep with apk. Pass the restricted executor 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