An OpenAI-hosted sandbox gives your agent a Linux workspace with Python, Node.js, and command-line tools. OpenAI provisions and connects it; your application supplies the task and retrieves the results. Choose a self-hosted sandbox when you need your own image, compute, or private network.
Configure the sandbox
Set environment.type to openai_hosted and add only the settings your workload
needs. The working directory is /workspace.
packages: Install Python, system, or globalnpmpackages withpython,system, ornpmlists. Pin versions when needed, such aspandas==2.2.3.setup_commands: Run ordered shell commands before the agent starts, such as[{ "command": "mkdir -p reports" }]. Each command has its own optionalcwd, defaulting to/workspace.files: Supply input files by Files API ID or inline base64 content.env: Set string-valued environment variables. Runtime-reserved names, includingPATH,CODEX_*, andOPENAI_API_KEY, are rejected.skills,plugins,capability_directories: Add skills and plugins.environment_template_id: Reuse saved configuration across sessions. Omitted settings inherit the template; network overrides cannot broaden its policy.
Packages and input files are prepared before setup commands run. A nonzero setup exit status prevents the agent from starting. Use a setup command to check required dependencies or files. Templates save configuration, not a running workspace.
Control network access
network.access | Behavior |
|---|---|
enabled | Allow outbound access. This is the default unless you inherit a template policy. |
disabled | Block outbound access. |
restricted | Allow only the hosts listed in allowed_domains. |
Restricted mode accepts 1–100 exact host names, such as api.example.com.
Do not include wildcards, protocols, paths, or ports. Subdomains and redirect
destinations need their own entries. Hosted stdio MCP servers currently require
enabled access; see stdio MCP requirements.
Check that setup succeeded
The create-session response means setup has started. Retrieve
GET /v1/agents/environments/{environment_id} using the session’s environment.id:
provisioning means setup is running; connected means setup succeeded.
For failed, read environment.error in the agent.session.environment.failed
event. Wait for connected before adding or listing live files.
Files and lifetime
Each session has a separate workspace. Files persist across turns while its
sandbox exists. Files under /workspace/outputs are published as immutable
artifacts when a turn completes; those copies remain downloadable after the
sandbox expires.
Use Files and artifacts for uploads, path rules, live file operations, downloads, and limits. Save outputs you need before deleting the session.
Sandbox expiry
Connected sandboxes receive keep-alives, including between turns. If activity and keep-alives stop for an hour, the sandbox can be deleted. This timeout isn’t configurable.
Delete the session when you’re done to request sandbox cleanup. If deletion
returns 409 while setup or execution finishes, wait and retry with a limit on
the number of attempts. Closing an event stream does not cancel the task.
Pricing
OpenAI-hosted sandboxes use standard container rates. Model usage is billed separately at the selected model’s API rates.
Example: Create a report
Give the agent a CSV containing 10, 20, and 30. It runs Python to calculate
the sum and writes /workspace/outputs/summary.json.
Set OPENAI_API_KEY in your application terminal using the
quickstart prerequisites.
Keep this key outside the sandbox. Use a version of your
OpenAI SDK that includes the beta Agents API.
from openai import OpenAI
client = OpenAI()
stream = client.beta.agents.sessions.create(
agent={"model": "gpt-6-astra"},
environment={
"type": "openai_hosted",
"network": {"access": "disabled"},
"files": [
{
"type": "inline",
"path": "/workspace/amounts.csv",
"data": "YW1vdW50CjEwCjIwCjMwCg==",
}
],
},
input="Use Python to sum the amount column in /workspace/amounts.csv. Write a JSON object with the total to /workspace/outputs/summary.json, then read it back to verify it.",
stream=True,
)
with stream:
for event in stream:
print(event.model_dump_json())The base64 value in files contains the CSV input. The code prints session events.
Save session.id from agent.session.created. After agent.session.turn.completed,
list the artifacts, find summary.json,
and download it. Its contents should be:
{ "total": 60 }
A completed turn does not guarantee every tool succeeded. If the task fails or the stream ends before completion, inspect the saved session items. Delete the session when you’re done.
Troubleshooting
| Problem | What to check |
|---|---|
| Setup fails | Inspect the environment-failure event and fix the package, input-file, or setup-command error before creating another session. |
| A sandbox request is blocked | Check network and any hosts reached through redirects. |
| A live file operation fails | Confirm the sandbox is connected. If it expired, create a new session and supply the inputs again. |
A status or file-list request returns 5xx | Retry with increasing delays and a deadline. Keep the request ID if the error persists. |