OpenAI Agents API: What a Self-Hosted Sandbox Does—and Does Not—Control

Choosing a self-hosted sandbox in the OpenAI Agents API does not move the whole agent into your infrastructure. Your machine runs commands and handles files; OpenAI still runs the Codex harness that manages the model-and-tool loop. For a backend developer trying to remove a homegrown agent loop without giving up private-network execution, that split is the central integration decision. The public beta offers an execution choice, not a promise of entirely local processing.

OpenAI’s September 10 changelog confirms the public beta. The documentation reviewed on September 11 describes durable sessions, managed context compaction, recovery, and a choice of execution environments. This is a documentation-based launch interpretation, not a SandBase performance test or a claim that SandBase exposes this API.

Key takeaway

• OpenAI runs the Codex harness even when the execution environment is self-hosted.
• An environment is optional: remote MCP tools and application-handled functions can work without a built-in shell or workspace.
• Self-hosted execution leaves provisioning, reconnection, shutdown, and file preservation with your application.
• The current Agents API supports US data residency only and does not support Zero Data Retention, including with a self-hosted sandbox.

The overview and architecture documentation establish those boundaries. They matter more to an initial adoption decision than whether the first example can print a useful answer.

OpenAI Agents API self-hosted sandbox limits start with the harness

The architecture page puts the division plainly:

“OpenAI runs the agent harness. Your application sends it work and receives results.”

The harness is the software around the model: it maintains the session and runs the sequence of model decisions and tool calls. The environment is where commands execute and files live. Your application server submits tasks, receives events, handles function tools, and, when you provide the environment, manages that environment’s lifecycle.

Consider a hypothetical repository investigation service. A user asks it to identify why a build failed. The execution environment may need a checkout, dependencies, and permission to read internal build logs. The agent session needs the request, intermediate findings, and subsequent questions. Hosting the checkout yourself addresses the execution location; it does not establish that all session information remains on that machine.

That is the reason to draw these components separately in an architecture review. “Self-hosted agent” would collapse two different ownership choices into one reassuring but inaccurate label. Describe the planned system as an OpenAI-managed harness connected to your execution environment, then review what each component receives.

OpenAI’s architecture documentation separates the managed harness from the execution environment and lists the tools unavailable with none. Source: OpenAI, captured September 11, 2026.

Pick an environment for the work the agent actually needs

The documented environment choices are not three levels of intelligence. They decide whether the agent has compute and files, and who maintains them.

Environment	Appropriate starting task	What changes for your application
none	Answer through remote MCP or application functions	No built-in Bash, apply-patch, workspace files, or executor MCPs
openai_hosted	Run scripts, edit files, produce artifacts in a managed sandbox	Configure packages, initial files, and network access; OpenAI manages the sandbox
self_hosted	Work with your infrastructure, private network, or custom software	Provision compute, connect an executor, handle lifecycle and preserve needed files

These are the choices in OpenAI’s architecture guide, not results of a comparative benchmark.

A read-only documentation assistant is a useful example of where none may fit. If all information arrives through a remote MCP server or a function your backend implements, adding a shell creates another component to configure without necessarily helping the task. MCP—Model Context Protocol—is the interface through which the agent can discover and call an external service’s tools.

Conversely, a task that edits a repository cannot assume it has a filesystem merely because it uses an agent API. With none, the built-in workspace and shell are absent. OpenAI describes an optional virtual runtime implemented through application functions, but building that is application work, not a hidden sandbox supplied by the setting.

For a first integration, choose the smallest environment that supports the required action. This is an engineering recommendation, not a vendor claim that one mode is universally safer or cheaper.

A saved agent is not the session containing the work

The configuration guide distinguishes reusable agent settings from a session’s conversation and work. Model, instructions, tools, and reasoning settings can be supplied for one session or saved for reuse. Multiple sessions can use a saved agent without sharing one conversation.

This makes two application records useful: the reusable agent configuration and the individual job-to-session mapping. For example, a release-note assistant could reuse its instructions across repositories while giving each investigation its own session. The application should decide which user is entitled to continue each session; a reusable configuration is not itself a tenant-access policy.

One easily missed detail is how overrides behave:

“Supplied objects and arrays replace the entire field rather than merging with the saved value.”

OpenAI explicitly gives tools as an example. If a saved agent has several tools and a session supplies a new tools array, that supplied array replaces the list. It is not an instruction to append one tool.

Before sending a per-session customization, construct and inspect the complete intended tool list. Otherwise an application can silently remove a required capability while believing it added another. The documentation also says credentials stay in vaults, separate from saved agent configuration; it does not justify placing secrets in instruction text.

The official session-override example is followed by the replacement rule: a supplied tools list replaces the saved list. Source: OpenAI, captured September 11, 2026.

Self-hosted execution still needs a lifecycle owner

For self_hosted, your code starts the environment and connects an executor. The executor carries out commands and tools requested by the managed harness. OpenAI says the application manages the connection and lifecycle without forwarding every command itself.

That reduces one kind of integration work, but the documented responsibility for provisioning, reconnection, shutdown, and file preservation stays with the application. A successful session-creation response should therefore not be treated as proof that your worker is ready or that its files will survive teardown.

OpenAI’s specific shutdown advice is to coordinate incoming work and confirm that no execution is pending before stopping compute. This changes the implementation question from “Did the HTTP request finish?” to “Can this session still receive or execute work?”

For a repository analysis product, a sensible acceptance exercise would be to disconnect its executor during a bounded read-only task, reconnect it, and inspect the resulting session and files before teardown. That exercise has not been performed for this article. It is a proposed integration check, not evidence that recovery will satisfy a particular timeout or availability target.

Keep a separate decision for exporting the result. The durable session described by the API and the files your own environment must preserve are different things. If the user’s deliverable is a patch or report, the application needs an explicit point at which it verifies and retains that deliverable.

Progress events do not replace function handlers

The API supports streaming for detailed progress and webhooks for session state changes. OpenAI says an application can use either or both. That lets a product separate a live progress display from the backend work that continues when no browser is watching.

But function tools still need application code to receive calls, perform the action, and return results. The architecture guide warns that an unavailable handler can leave the agent waiting. Event-handler or lifecycle-handler failures can also interrupt progress updates or environment management.

For example, a hypothetical issue investigator might request an internal build-log lookup. The managed harness can request that function; it cannot make your missing handler return the log. Distinguish “waiting for a tool result” from “model is still thinking” in the application’s state display and operational logs.

Remote MCP tools are a different documented path: the harness can call them directly. Do not copy the lifecycle assumptions of an application-handled function onto every MCP connection. Identify the actual tool transport and failure owner before designing a retry or user-facing error message.

Self-hosting does not remove the current retention restriction

The overview’s data-controls notice is explicit: the Agents API retains session state, currently supports data residency only in the United States, and does not support Zero Data Retention (ZDR). Choosing a self-hosted sandbox does not make it ZDR-eligible.

ZDR means Zero Data Retention, a specific data-control arrangement; it is not another name for placing a container in your own cloud account. The guide also says sessions and published artifacts can be deleted when no longer needed. That deletion capability should not be rewritten as a claim of no retention.

For a developer whose requirement is “execute against software in our private network,” self-hosting is relevant to evaluate. If the requirement is “use this API under ZDR,” the documented answer is no at the time of this review. These are separate requirements, even if both arise in the same procurement discussion.

This article does not establish exact retention durations, contractual exceptions, or approval for a particular regulated workload. Follow the linked platform data controls before making those decisions.

Budget for components, not a fictional flat agent price

The overview describes three billing categories: selected-model API rates, standard OpenAI tool rates, and standard container rates for OpenAI-hosted sandboxes. It does not present the product as a single fixed price per completed task.

For planning, record which model and tools a workflow will use and whether it requires a hosted sandbox. If execution is self-hosted, separately account for the infrastructure you operate. Do not conclude that “no OpenAI-hosted sandbox” means “no agent cost”: model usage remains part of the documented billing model.

No per-task bill, latency distribution, or savings percentage was measured here. A cost comparison should use accepted task outcomes under declared settings, not just one model’s token price.

The overview names model, tool, and hosted-container rates separately; it does not quote a flat price per agent task. Source: OpenAI, captured September 11, 2026.

When to evaluate it—and when to pause

Evaluate the beta if your immediate goal is to use a managed Codex session and tool loop while selecting where commands run. Start with a non-sensitive, bounded task and check three concrete outcomes: whether the right tools are available, whether interrupted execution is represented correctly, and whether the expected deliverable survives completion and teardown.

Pause if your requirement depends on ZDR or non-US data residency for this API. Also pause a production rollout if no component owns function responses and self-hosted environment cleanup. Managed orchestration is not a substitute for those application responsibilities.

For readers coming from the Codex App Server integration article, this is a different deployment decision: here the subject is the managed API, not embedding a local client-facing server. The next useful step is OpenAI’s Agents API quickstart, followed by an explicit review of the environment and data boundary your application can accept.