OpenAI Agents SDK sandbox: setup, persistence and cost

Do not index

An OpenAI Agents SDK sandbox gives your agent a workspace for running commands and changing files while your application controls the agent loop. You can connect that workspace to Agent37 through its documented Python client, then choose standard gVisor compute or a full VM according to the workload. Model calls, sandbox compute and retained storage are separate costs.

The first decision is what must survive after the answer arrives. A disposable code check can delete its workspace immediately. A customer project needs files, ownership records and a recovery path that outlast one model run.

This guide walks through that decision, a small Python example, and the cost of keeping the workspace. Sources and rates were checked on November 9, 2026.

Choose your OpenAI Agents SDK sandbox boundary

The SDK and the managed Agents API are different deployment choices. With the SDK, you operate the application that calls the model. With the Agents API, OpenAI operates the harness and manages sessions, orchestration and recovery. Choose the service you intend to operate before copying a sandbox example. OpenAI Agents API overview.

For SDK sandbox agents, the main pieces are SandboxAgent, a Manifest describing the starting workspace, a provider client, and per-run sandbox configuration. Current SDK documentation covers Python and TypeScript. Provider support determines which execution and storage features are available. OpenAI sandbox-agent guide.

Our recommendation is to keep the trusted application outside the worker that runs generated code. That application should own customer authorization, model credentials, spending limits and the mapping between a customer and their instance.

For example, a report service can send a small CSV into a worker, let the agent analyze it, then retrieve and validate the resulting JSON. The worker has no reason to hold the account database credentials or decide which customer's files to load.

If the task only needs a text response, a separate workspace adds operational work without helping the result. Add it when commands, dependencies or artifacts are part of the job.

Pick a runtime and check the client limits

Start with a standard Agent37 sandbox for ordinary Python, Node.js and repository tasks. Standard instances use gVisor and share host resources. They cannot run a Docker daemon.

Choose a full VM when the job needs Docker, Compose or its own Linux kernel. Agent37's Ubuntu VM template includes Docker. VM compute costs more, and an entrypoint expecting systemd is unsupported. See the VM documentation.

The Agent37 SDK integration supplies a Python client as one source file. It uses the plain agent37-base template by default; an additional coding-agent harness inside the instance is unnecessary.

Check the adapter before planning the product around it. The documented client does not support PTY sessions, exposed ports or storage mounts. Its commands run as root, with a fresh shell for each command. A preceding cd or shell variable will not carry into the next command.

Those limits matter. A batch report fits this path more naturally than an interactive terminal product. Platform capabilities and adapter capabilities need separate checks.

Run one small job and retrieve its artifact

Use a funded Agent37 workspace and keep AGENT37_API_KEY, OPENAI_API_KEY and your chosen OPENAI_MODEL in the application environment. Do not put these values into a prompt or commit them with the example.

Create an isolated Python environment and install the versions used for this guide's offline checks:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install openai-agents==0.24.0 httpx==0.28.1

Save the complete client from the integration documentation as agent37_sandbox.py beside your script. That is provider-specific integration code, so keep a reviewed copy with your application and retest it when upgrading the SDK.

This example asks for a tiny, independently checkable artifact. It keeps the session open long enough to read the file, checks the result in the trusted application, and then exits the session context.

import asyncio
import json
import os
from pathlib import Path
from agents import Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agent37_sandbox import Agent37SandboxClient, Agent37SandboxClientOptions

async def main():
    client = Agent37SandboxClient()
    options = Agent37SandboxClientOptions(create_options={
        "resources": {"cpu": 2, "memory": 4, "disk": 4},
        "network": "deny-all",
    })
    agent = SandboxAgent(
        name="Small report worker",
        model=os.environ["OPENAI_MODEL"],
        instructions="Use the workspace. Verify the file before answering.",
    )
    manifest = Manifest(root="/home/node/workspace")
    async with await client.create(manifest=manifest, options=options) as sandbox:
        await Runner.run(
            agent,
            'Write report.json containing {"total": 10}, then read it back.',
            run_config=RunConfig(sandbox=SandboxRunConfig(session=sandbox)),
        )
        with await sandbox.read(Path("report.json")) as artifact:
            report = json.load(artifact)
        if report != {"total": 10}:
            raise ValueError("Unexpected report")
        print(report)

asyncio.run(main())

The application needs network access to OpenAI and Agent37. The worker itself does not need outbound access for this task. Agent37's deny-all policy blocks worker egress while its command API remains available. Dependency downloads would require a different policy or a prepared template. Network access reference.

We checked imports, configuration, syntax and selected client behaviors with mocked HTTP responses. We did not run a paid model turn for this article. Run this small job in your account before replacing it with customer data or a larger task.

Decide who owns the workspace after the run

A persistent platform does not mean every integration keeps instances forever. Lifecycle behavior comes from the code that creates and closes the session.

In the documented Agent37 client, a newly created instance belongs to that client session. Leaving the context deletes it. The simple runner-managed pattern also cleans up its created instance when the run ends. An attachment to an existing instance is treated differently: closing that session does not delete the attached instance. SDK lifecycle examples.

Job	Suggested ownership	Completion rule
One report or code check	A new disposable instance	Copy and validate output before cleanup
Several steps in one request	One explicitly managed session	Reuse it until all required artifacts are collected
A project reopened tomorrow	An application-owned instance	Store its ID, attach on return, apply a retention policy

Saving an instance ID inside a context that subsequently deletes the instance will not preserve the project. Provision and retain the instance deliberately, then use attachment when another application process returns.

For workspaces that must survive image updates, place files on the configured persistent disk. The example sets its root under /home/node, the default disk mount for system templates. An arbitrary directory elsewhere is not equivalent. Check the create-instance persistence settings.

Treat conversation history, files and running processes as separate recovery requirements. A useful recovery test starts a fresh application process, reconnects to the intended instance and verifies a known file before asking the model to continue. Do not judge recovery solely by whether the agent says it remembers the task.

Calculate compute, retained disk and model spend separately

For a 2 vCPU, 4 GB RAM standard instance, the current compute rate is $4.40 per 730 running hours. Four GB of disk costs another $0.36 per 730 hours of retention. Full VM compute is 2.5 times the standard rate, with the same disk rate. Current pricing.

The following estimates use one instance, 2 vCPU, 4 GB RAM and exactly 4 GB disk. They exclude model calls, paid tools, the application server and any other services. These are resource budgets, not performance benchmarks.

Runtime and retention	60 running hours	730 running hours
Standard, delete after the running period	$0.39	$4.76
Standard, retain disk for all 730 hours	$0.72	$4.76
Full VM, delete after the running period	$0.93	$11.36
Full VM, retain disk for all 730 hours	$1.26	$11.36

For the second row, the calculation is (4.40 × 60 / 730) + 0.36 = $0.7216, rounded to $0.72. The same workload with deletion after 60 hours is 4.76 × 60 / 730 = $0.3912.

An awake worker waiting on a model still incurs compute charges. Stop or sleep pauses compute; retained disk continues billing. Auto-sleep must be enabled, and deleting the instance ends its meter. Actual billing uses minutes. Billing reference.

The Ubuntu VM defaults to 12 GB disk when omitted, making its 2 vCPU, 4 GB RAM estimate $12.08 for 730 hours. The table deliberately specifies 4 GB. Check the resource request before treating any example as your invoice.

Test failures before adding more workers

The happy path proves that an agent can produce an answer. It does not prove that your service returns the right artifact, contains failures or stops paying for abandoned workers.

Use a small acceptance suite with concrete outcomes:

Artifact failure: request invalid JSON or a missing file. The application should report failure and preserve enough diagnostic information to investigate. It should not mark a job successful because the model's final message sounds confident.

Command timeout: use a harmless command that exceeds a short execution deadline. Verify the error, inspect whether work is still running, and check cleanup separately. A client connection failure leaves a different recovery question from a confirmed command timeout.

Application restart: interrupt your orchestrator between artifact creation and acknowledgment. Your job record should let a replacement process discover whether output already exists. Retrying a report is usually cheap; repeating a payment or external write can have consequences.

Tenant boundary: try to load another test customer's instance ID through your application. Reject that request before sending it to the provider. A valid infrastructure credential is not proof that the current customer owns the resource.

Retention expiry: create a disposable test project with a short retention period. Verify that your cleanup process deletes the intended instance and marks the job record accordingly. Test this through the same path production will use.

For broader boundary design, see our agent sandboxing guide.

Keep production recovery independent of the worker

Keep a durable record of the job ID, customer ID, instance ID, lifecycle ownership and artifact status outside the worker. Record whether a retry should resume existing work or create a fresh workspace. This makes recovery decisions inspectable without asking the model to reconstruct events.

For longer workflows, Agent37 documents a Temporal integration that registers its sandbox client on the worker. That can help organize durable orchestration, but it does not remove your responsibility for retention or duplicate external side effects. Start with explicit ownership and retry rules before adopting another service.

Monitor useful outcomes: completed jobs, validated artifacts, failure reasons, retained instances and cost per completed job. A cheaper hour can still produce an expensive result if jobs repeatedly restart or leave workspaces awake.

Begin with a single representative task in the Cloud dashboard, then follow the SDK integration guide. Confirm the artifact, cleanup and bill before increasing concurrency.

Frequently asked questions

Does the SDK require a hosted sandbox provider?

No. OpenAI documents local, Docker and hosted-provider clients. Choose hosted execution when your product needs infrastructure beyond the developer machine, then verify that provider's adapter supports the required operations.

Is this the same as running Codex on Agent37?

No. This setup runs your application with the Agents SDK and sends workspace operations through a sandbox client. A preinstalled coding-agent template is a separate way to run an agent.

Can I use the standard sandbox for Docker builds?

A Docker daemon requires a full VM on Agent37. Use the Ubuntu VM template or an appropriate custom VM template, and include its higher compute rate and chosen disk size in the budget.

Will stopping a sandbox erase the project?

Agent37 retains the billed disk while stopped, but process memory is a separate concern. Keep durable files on that disk, preserve the application job record, and test a cold start. Deletion is the cleanup action for an instance you no longer need.