How to Configure OpenAI Hosted Sandboxes Network Access? 2026 Agent Security Deployment Guide

Default to no network access, and open only the connections the task can prove it needs.

If the Agent must reach a private API, database, or internal service, evaluate a self-managed environment or controlled gateway before expanding Hosted Sandbox permissions.

This guide is for:

• Independent developers moving a code-execution Agent from a demo to repeatable jobs.
• AI application engineers who need dependencies, file access, and business API calls.
• Platform engineers responsible for network egress, credentials, isolation, and audit boundaries.

The deployment decision

OpenAI Hosted Sandboxes can provide a managed Linux workspace for file handling, code execution, and dependency configuration. The relevant question is not whether an Agent can run code. It is whether the code needs a network path, which destination it needs, and whether the managed boundary is sufficient for the data involved.

The official OpenAI Agents API introduction describes the broader Agent architecture, while the Sandbox Agent guide documents the environment model and workflow. Use those documents as the authority for currently supported environment fields and connection behavior. Do not treat a community example, an old code sample, or a future capability discussion as a security guarantee.

Use this decision rule before writing configuration:

• If the task only transforms supplied files or performs local computation, choose a no-network Sandbox design.
• If the task installs approved packages or reaches a public API, choose a controlled outbound path with an explicit destination and a repeatable connectivity test.
• If the task reads a private database, calls an internal service, or handles sensitive enterprise data, prefer a self-managed environment or a backend gateway unless the current Hosted Sandbox documentation and your security review confirm an adequate boundary.
• If the task needs a durable workspace, custom routing, long-lived processes, or low-level system administration, compare a cloud development environment or remote Mac with the managed Sandbox rather than forcing the Sandbox to act like a general server.

This approach prevents a common procurement mistake: choosing the most permissive environment before identifying the actual workload.

Network configuration boundaries

Think of network access as four separate use cases, not one switch.

Local file computation needs a workspace, input files, runtime tools, and output collection. It does not automatically need the public internet. A document conversion Agent, for example, should not gain outbound access merely because the model might find it convenient.

Dependency installation needs access only during environment preparation, and even that access should be controlled. Installing packages at runtime makes behavior dependent on repository availability, package changes, DNS, certificates, and the model's command choices. A repeatable build should make the dependency set explicit before the Agent receives production input.

Public API access is narrower than unrestricted internet access. A weather, search, translation, or repository API may require outbound HTTPS, but the Agent still does not need permission to contact arbitrary hosts. Use an application-level client or gateway when you need request validation, rate controls, response filtering, or audit records.

Private service access has the highest review burden. A database or internal webhook is not simply another URL. It introduces identity, data classification, lateral movement, and operational recovery risks. Put a service boundary between the Agent and the private system whenever possible.

The Agents SDK tool documentation is useful for separating a model-facing tool from the implementation that performs the action. Expose a narrow function such as “create report from approved dataset,” not a general-purpose request function that accepts arbitrary hosts, headers, and query parameters.

Scenario: a customer-report Agent

Suppose an Agent receives CSV files, cleans them with Python, and sends a summary to an internal reporting service. The file cleaning portion can run without network access. The reporting call should not receive a permanent internal token through the prompt. A safer design is:

1. The Sandbox processes the supplied files.
2. The Agent produces a structured report artifact.
3. A controlled backend validates the artifact and the requested report operation.
4. The backend authenticates to the internal service.
5. The response returned to the Agent contains only the fields required for the next step.

This design also makes failure attribution easier. A rejected report request is a backend policy event, not an ambiguous model error.

Workspace and dependency control

Network settings cannot compensate for an incomplete runtime. Before debugging outbound access, establish what the workspace contains and how it is created.

The official Sandbox Agents documentation should be checked for the current environment lifecycle and client behavior. In your own configuration, record these items:

• The working directory used for input, temporary files, and final artifacts.
• The Python runtime and the package installation method.
• The Node.js runtime and the npm or equivalent package source.
• Required system utilities and whether they are available during setup.
• Startup or setup commands that run before the Agent task.
• Writable directories and directories that must remain inaccessible.
• The version or checksum of each dependency set.
• The output path and the mechanism used to download artifacts.

Install stable dependencies during environment preparation when the workflow supports it. Do not let the model decide at runtime that an unreviewed package, shell utility, or package mirror should be added. A model can identify a missing import, but it should not automatically expand the software supply chain.

Use a minimal verification task before real work:

• Import each required Python package.
• Run the expected Node.js command.
• Invoke every system binary needed by the workflow.
• Read a test file from the intended working directory.
• Write a test artifact to the approved output directory.
• Attempt a connection only to the explicitly approved endpoint.
• Record the command result and environment state.

A successful import does not prove that the package is usable. It may still fail because of a missing shared library, an incompatible runtime, a certificate problem, or a working-directory assumption. Verify the action the Agent will actually perform.

The Sandbox client reference should be your starting point when environment creation, setup commands, or client-side state handling differs from an example in a blog post.

External API and private-service access

Public endpoints and internal systems require different controls.

For a public API, define the destination, protocol, authentication method, timeout, response size, and retry policy. Avoid passing arbitrary URL input from the model directly to a network client. If the model must choose among several services, expose those services as separate tools or as an allowlisted operation.

For a private API, use a gateway that can:

• Validate the requested operation and input schema.
• Reject unapproved hosts and paths.
• Apply tenant and user authorization.
• Issue short-lived credentials or sign the request server-side.
• Remove sensitive headers from responses and logs.
• Enforce timeouts, request limits, and replay protection.
• Return an audit identifier without returning secret material.

For a database, do not give the Agent broad SQL access unless the risk has been explicitly accepted. Prefer read-only views, stored procedures, or task-specific query tools. A database credential in an environment variable is still exposed if the model can execute commands and print that variable.

For a webhook, validate the payload before delivery. The Agent should not be able to select arbitrary recipients or modify authentication headers. If the webhook is a business action, require an approval step outside the model context.

API keys should never be placed in prompts, uploaded configuration files, generated source code, shell history, or model-readable logs. The key may leak through an error message, a debugging trace, or a final artifact even when the main prompt is carefully written. A proxy is valuable because it keeps the long-lived secret outside the Sandbox and turns the Agent's request into a policy-controlled operation.

Failure diagnosis

Treat network failure as a sequence of observable checks rather than asking the Agent to “try again.”

1. Environment creation failure

Confirm that the Sandbox was created and that the expected environment state is available. If creation fails, network debugging is premature.

1. Connection refusal or blocked egress

Test the approved destination with a harmless request. A refusal may indicate a policy boundary, an unavailable service, an incorrect port, or a gateway rule.

1. DNS failure

Separate name resolution from transport. Record the hostname, resolver result, and exact error. Do not immediately replace the hostname with an IP address, because that can break TLS validation and bypass intended routing.

1. TLS or certificate failure

Check the endpoint certificate chain, system trust store, hostname, and runtime configuration. Avoid disabling certificate verification as a troubleshooting shortcut.

1. Authentication failure

Confirm that the request reached the intended service and that the credential scope is correct. Redact authorization headers before storing logs.

1. Dependency installation failure

Determine whether the package source was reachable, whether the package version exists, and whether a system library is missing. Separate setup failures from application failures.

1. Timeout or stalled Agent task

Inspect the command output, request timeout, retry behavior, and service response. A timeout may come from a slow external system, a deadlocked process, or an Agent repeatedly choosing the same failing action.

Save the environment state, error event, command output, input-file version, dependency manifest, endpoint, and task identifier. These records let you distinguish three causes:

• A configuration error, such as a missing setup command or blocked destination.
• An external service problem, such as an outage or rejected credential.
• An Agent judgment error, such as using the wrong endpoint or retrying an unsafe action.

Do not include raw secrets in the evidence package. Redaction must happen before logs leave the execution boundary.

Security controls before launch

A production review should cover more than the network.

Network egress: List permitted destinations and protocols. Reject arbitrary host input. Confirm that an unapproved endpoint fails in a predictable way.

File access: Define the input, temporary, and output directories. Include a test that tries to read a neighboring or unrelated file. The expected result must be denial, not an empty response that could be misinterpreted.

Package versions: Record the dependency manifest and the setup output. Rebuild the environment from the same inputs before accepting a release.

Credentials: Confirm that prompts, files, shell output, traces, and artifacts do not contain secrets. Test expired, missing, and insufficient credentials.

Logs: Capture enough information to reconstruct a failure while filtering authorization headers, tokens, private payloads, and sensitive file contents.

Artifacts: Restrict which files can be downloaded or returned to the user. A report can be safe while a temporary directory contains credentials or intermediate data.

The Agents SDK quickstart is appropriate for validating the basic Agent flow. It is not a substitute for your own boundary tests. A quickstart proves that a workflow can run; it does not prove that the workflow is safe for private data or unrestricted tools.

Deployment choices by workload

Use the following decision conditions before selecting an environment:

• If all inputs are supplied at runtime and the task is deterministic, choose a restricted Hosted Sandbox.
• If package installation is required but the package set is stable, prepare the environment before the task and test each dependency.
• If a public service is required, use controlled egress or a proxy with an allowlist.
• If a private API or database is required, use a gateway first; move to self-hosting when the gateway cannot provide the required boundary.
• If the Agent needs persistent files, custom network routes, long-running processes, or interactive administration, evaluate a managed cloud workspace or remote Mac.
• If physical interfaces, local credentials, or a specialized desktop tool are mandatory, Hosted Sandboxes are not the right long-term environment.

This table is a planning aid, not a claim that every environment supports every network mode. Verify the current OpenAI documentation before implementation.

Pre-launch decision checklist

Before approval, run the following checks in order:

1. Define the task without granting network access.
2. List every external destination the task genuinely needs.
3. Move private calls behind a controlled backend where possible.
4. Prepare and pin dependencies before production input arrives.
5. Test workspace reads, writes, denied paths, and artifact collection.
6. Test missing, expired, and insufficient credentials.
7. Test an approved endpoint and an unapproved endpoint.
8. Preserve redacted state and error evidence.
9. Decide whether the remaining requirements fit Hosted Sandboxes.
10. Record the fallback environment before launch.

Hosted Sandbox versus a remote Mac

A Hosted Sandbox is a strong fit when you need isolated code execution, disposable workspaces, controlled file processing, and a narrow Agent tool surface. It is less suitable when the workload depends on a persistent development machine, customized routing, desktop applications, physical interfaces, or long-lived interactive sessions.

A remote Mac can provide a more complete workspace for those cases, but it also creates responsibilities that a managed Sandbox may abstract away: operating-system updates, user access, network policy, credential storage, process cleanup, and host-level monitoring. You should not rent or provision one simply to avoid writing a basic allowlist.

The comparison changes when your current setup is a developer laptop or an ad hoc cloud VM. A laptop exposes local files and personal credentials to a workflow that may be difficult to reproduce. A general VM often leaves you responsible for patching, firewall rules, persistent secrets, and cleanup after failed Agent runs. If the task needs a durable Mac-based environment rather than a disposable execution boundary, review kvmboot's remote Mac information and compare the operational scope before committing.

For temporary testing, a remote environment can be more convenient than rebuilding a local machine. You can also review kvmboot's support resources before deciding whether the required workflow is better served by a managed Mac workspace.

If you need a complete remote Mac for a long-running development session, graphical tooling, or custom network administration, kvmboot's available Mac environment may be a better operational fit than stretching a Hosted Sandbox beyond its intended boundary. The right choice depends on persistence, access control, and whether you can operate the host securely—not on the assumption that one environment is universally safer.

Start with the network and credential checklist above. Then compare the managed Sandbox against your own requirements for repeatability, private connectivity, dependency control, and workspace lifetime. That sequence will tell you whether to keep the Agent restricted, add a controlled gateway, or move the workload to a more configurable cloud Mac environment.