OpenAI Agents API Beta: Three Sandbox Options and Where Your Keys, Files and Data End Up

The OpenAI Agents API is in beta. It lets your application hand a task to an OpenAI-managed Codex agent that works across several steps and continues in the same session. OpenAI runs the agent loop. You choose where its shell commands and file edits run: nowhere, an OpenAI-hosted sandbox, or a sandbox you host. That choice decides where your files live, which keys you create, and how much you have to clean up yourself.

I read three primary pages: OpenAI's Agents API beta FAQ, OpenAI's Databricks sandbox cookbook, and Cloudflare's guide for running Codex with the Agents API. I did not run any of it, I do not have beta access to test, and I did not read OpenAI's Agents API overview or architecture pages. Everything below is what those pages say.

What it is

Per the FAQ, your application supplies the task, tools and configuration, and OpenAI manages the session and the coordination between the model and the tools. Depending on tools and environment, an agent can run code, edit files, use MCP connections and produce files for your app. You can send more instructions or a new task into the same session.

Requests need the OpenAI-Beta: agents=v1 header. The FAQ says OpenAI's SDKs add it automatically.

The three environment options

The FAQ lists them:

• No environment. The agent answers questions or calls external tools, with no built-in shell or workspace files.
• OpenAI-hosted sandbox. For scripts and file work, with OpenAI managing the sandbox.
• Self-hosted sandbox. For your own infrastructure, software or private network. The FAQ says your application manages the environment's lifecycle.

The two partner pages show what the self-hosted option looks like in practice.

Self-hosted, as the partners describe it

In Databricks' cookbook, the agent session is created with a self-hosted environment. Your application provisions the sandbox, then launches codex exec-server inside it. That process connects outbound to OpenAI and waits for tool calls. The agent then runs shell and file tools inside the sandbox. The cookbook says nothing needs to accept an inbound connection, so the app can run on a laptop, a Databricks job or a notebook.

Cloudflare's guide uses a different shape. OpenAI sends signed webhooks to a Worker in your account when a session starts, needs an environment, goes idle or fails. The Worker verifies each webhook and passes it to a Durable Object, which starts a container running codex exec-server. Files stay in /workspace in your Cloudflare account. The guide's template snapshots the container when the session goes idle and keeps an idle container for 30 seconds by default.

Both pages describe the same split: OpenAI runs the agent loop, you run the place where commands execute.

Keys: three kinds, and they must match

This is the part that will trip people up, and the pages are specific.

• The FAQ says to create an application API key and grant api.agents.read and api.agents.write for sessions, plus api.responses.write for model requests.
• The FAQ also says to keep your API key outside the agent's sandbox.
• For self-hosted sandboxes, Databricks and Cloudflare both use a separate executor key, passed to Codex in the sandbox as CODEX_API_KEY. Cloudflare says it needs api.model.read and api.agents.environments.connect. Databricks says it must belong to the same organization, project and user or service account as the session. Cloudflare says the same about both keys.

Databricks gives the failure mode: an executor using a general key is rejected with 403 missing required scope api.agents.environments.connect.

I would treat this as a design rule: the agent's sandbox gets the narrow executor key, and your application key never goes in.

Networking and IP allowlists

Databricks says its sandbox has unrestricted outbound egress and closed inbound ingress, and that both are currently unconfigurable. That is a statement about the Databricks sandbox, not about the Agents API in general. It means the agent can reach any public host from that sandbox.

If your OpenAI organization enforces an IP allowlist, the sandbox's egress IP must be on it, and OpenAI rejects traffic from unregistered IPs. Databricks warns that the egress IP is stable while a sandbox runs but can change after a stop and restart. So a sandbox that works on Monday can start returning 401 ... IP is not authorized after a restart.

Observability and failure handling

The FAQ says you can review a session under Logs in the Platform dashboard, by selecting Agents and searching the session ID. You can inspect turns, tool calls and subagent activity.

Two lines in the FAQ are worth keeping:

• If the event stream disconnects, retrieve the existing session and its saved items before retrying, so you know what happened before you submit more work.
• A completed turn does not mean every tool succeeded, and an idle session alone does not establish that the task finished successfully. Review the reported result.

Databricks adds that a turn is finished when the stream reports the main agent's turn as completed, failed or cancelled, and that you should read results back from the sandbox, then stop the executor and delete the session and sandbox.

Billing and data limits

• Billing: per the FAQ, model requests use the selected model's API rates, and OpenAI tools and OpenAI-hosted sandboxes use their applicable tool and container rates. The FAQ does not list numbers. It points to the API pricing page, which I did not read. For self-hosted sandboxes, the compute bill comes from your provider. Cloudflare's guide requires a Workers Paid plan with Containers access.
• Data: the Agents API keeps session state so work can continue across turns. You can delete sessions and published artifacts, and the FAQ says to save files you need before deleting a session.
• Residency and retention: the FAQ says the Agents API currently supports data residency in the United States only. It does not support Zero Data Retention, including with a self-hosted sandbox.

That last point matters if you were hoping a self-hosted sandbox would also give you Zero Data Retention. According to the FAQ, it does not.

What I would check

These are my untested suggestions, not results.

1. Key scope. Create the executor key with only the permissions the partner guides name, and confirm your application key never appears in the sandbox environment.

2. Restart behavior. Stop and restart a self-hosted sandbox, and confirm the egress IP and allowlist still work, and that codex exec-server reconnects.

3. Disconnect recovery. Kill the event stream mid-turn, retrieve the session, and check what the saved items show before you resend.

4. Success checking. Do not treat an idle session as done. Write a check that reads the output files and compares them to what you asked for.

5. Cost per task. Run a small fixed task ten times and compare the token usage in the session logs with the sandbox provider's bill.

What I would not conclude

• That a self-hosted sandbox keeps your data out of OpenAI's hands. The FAQ says session state is retained, and the agent loop runs at OpenAI.
• That the Databricks egress and ingress limits apply to every sandbox. They are Databricks' statement.
• That the beta is stable. It is labeled beta, and the examples I read use model name gpt-5.6-sol, which may change.
• That any of this matches your account. I did not test with an API key.

Frequently asked questions

What is the OpenAI Agents API?

A beta API for building applications around an OpenAI-managed Codex agent that works across multiple steps and keeps its session between turns.

Do I need a sandbox?

Not always. The FAQ lists no environment, an OpenAI-hosted sandbox, and a self-hosted sandbox. Pick based on whether the agent needs a shell or files, and who should run them.

Which API keys does it need?

An application key with api.agents.read, api.agents.write and api.responses.write, per the FAQ. Self-hosted setups also use a separate executor key, which Cloudflare says needs api.model.read and api.agents.environments.connect.

How do I see what the agent did?

Open Logs in the Platform dashboard, select Agents, and search the session ID. You can inspect turns, tool calls and subagent activity.

How is it billed?

Model requests use the selected model's API rates. OpenAI tools and OpenAI-hosted sandboxes use their tool and container rates. The FAQ points to the API pricing page for current numbers.

Does it support Zero Data Retention?

No, per the FAQ, including when you use a self-hosted sandbox. Data residency is currently limited to the United States.

What happens if the stream drops?

Retrieve the existing session and its saved items before retrying, so you can see what already happened.

Sources

All pages read on October 26, 2026.

• Agents API (beta) FAQ (OpenAI Help Center): environments, keys, logs, billing, data handling.
• Running OpenAI agents using a Databricks Sandbox (OpenAI Cookbook): application-managed lifecycle, executor key, networking, troubleshooting.
• Run Codex with the OpenAI Agents API in a sandbox (Cloudflare Sandboxes docs, last updated Oct 22, 2026): webhook flow, key permissions, idle behavior.

Not read: the Agents API overview and architecture pages, the API pricing page, and the full Databricks and Cloudflare guides past the sections cited.