Use Databricks Sandbox to run an agent’s shell commands and work with files in your Databricks workspace. Your application manages the sandbox. Its executor, codex exec-server, opens an outbound connection to OpenAI using the session’s environment.id and environment.remote_url.
Databricks Sandbox is in beta. Check that your workspace is in a supported region, then enable Databricks Sandbox on the workspace’s Previews page.
Before you begin
- Authenticate a Databricks profile for your workspace. Use its name in place of
my-workspacebelow. - Set
OPENAI_API_KEYto your application key andOPENAI_EXECUTOR_API_KEYto a separate environment key from the same organization, project, and user or service account. Only the environment key enters the sandbox asCODEX_API_KEY. - If your OpenAI organization enforces an IP allowlist, keep it up to date as sandbox outbound IPs change. For workspaces in the serverless compute firewall preview, follow the Databricks guidance for regional IP ranges.
Run the example
From the root of the OpenAI Cookbook repository, run the example with uv and Python 3.11 or later. Choose an unused sandbox ID because the example deletes the sandbox during cleanup.
uv run examples/agents_api/sandboxes/databricks/application_managed/main.py \
--profile my-workspace --sandbox-id "openai-agent-$(date +%s)"The example creates a self-hosted session, starts the executor in the sandbox, and asks the agent to write a greeting to a file. It reads the file back and prints Verified the agent's file write. on success. It then stops the executor and deletes the session and sandbox.