October 27, 2026 · Ahmed · More by Ahmed
Pre-Warming OpenAI Agent Sandboxes: Three Timers
OpenAI's Agents API lets you pre-warm sandboxes for lower latency and now bills compute only during active turns — but three separate expiry timers still apply.
Two changes, shipped on the same day
On October 9, 2026, OpenAI's Agents API changelog logged two connected updates to OpenAI-hosted sandboxes. The first: you can now pre-warm a sandbox — create and configure it before an agent session needs it, to cut the latency a user would otherwise wait through. The second, billed separately but shipped the same day: OpenAI-hosted sandbox compute is now billed only during active turns, and idle time between turns is no longer charged at all. For a pipeline that spins up many short-lived agent sessions, those two changes together mean sandbox lifecycle now has direct, separate consequences for both latency and cost — and they're governed by timers that are easy to miss if you only read the billing note.
The three-step pre-warm workflow
Pre-warming is a straightforward three-step sequence. First, create an environment with POST /v1/agents/environments, supplying the packages, files, and setup commands the task needs. Second, wait for readiness — either poll the environment until its status is ready, or subscribe to the agent.environment.ready and agent.environment.failed webhooks instead of polling. Third, start a session and pass the environment ID when creating it. You don't have to wait for setup to finish before attaching: you can attach an environment while setup is still running, and the agent's access to the workspace simply waits until setup completes.
Three timers, not one
The billing change is easy to read as "sandboxes are now free when idle," but that's only true for compute billing, and only in certain states. There are three distinct expiry timers, and they apply to different stages of a sandbox's life:
- Unattached pre-warmed sandbox: pre-warming itself is free, including container usage before attachment — but an unattached pre-warmed sandbox expires after exactly 5 minutes. Attach it before that window closes, or the workspace is gone and retrying the same environment ID won't restore it.
- Connected sandbox: once attached to a session, standard container pricing applies. A connected sandbox receives keep-alives, including between turns, but if activity and keep-alives stop for a full hour, the sandbox can be deleted. That one-hour timeout isn't configurable.
- Shared environment: a shared environment can support up to 128 attached sessions, and the first attachment starts a separate 20-minute idle lifetime. Activity in any attached session, or through the environment file API, extends that window; pending work and active turns prevent idle expiry. The environment has no standalone deletion endpoint — it only goes away once that 20-minute idle deadline is reached, even after the last session attached to it is deleted.
Designing around the timers, not just the bill
For an automation pipeline that creates a fresh agent session per task, the practical takeaway is to treat pre-warming as a narrow, time-boxed optimization rather than a standing pool. Create the environment close to when you expect to need it, confirm readiness through the ready webhook rather than guessing, and attach it inside that 5-minute window. Once attached, the no-idle-billing change means you're not paying for the gaps between turns — but you're still on the hook for the one-hour connected-sandbox timeout if a session goes quiet, and for the 20-minute idle clock if you're reusing a shared environment across many sessions. Tracking environment status explicitly, rather than assuming a sandbox will simply wait for you, is what keeps a high-throughput pipeline from either losing pre-warmed work or holding onto sandboxes longer than it needs to.