All guides
OpenAI

Runloop

Checked 09/15/2026View original
English original
On this page

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.

See the application-managed example in the OpenAI Cookbook.

This guide uses application-managed provisioning: your application starts the Devbox, connects its executor, and shuts it down when finished. See Sandbox lifecycle for the lifecycle behavior.

Before you begin

Use the Runloop SDK or API to manage a Devbox, and HTTP requests to manage Agents API sessions.

Set RUNLOOP_API_KEY and use OPENAI_API_KEY for application requests. Set OPENAI_EXECUTOR_API_KEY to an environment key, and pass only that key into the Devbox as CODEX_API_KEY.

Application-managed

  1. Create a self-hosted session and save its environment ID.
  2. Create a Runloop Devbox with the session's working directory and install the Codex CLI inside it.
  3. Start the executor in the background with the environment ID and environment key.
  4. Send input and inspect the result. For a file task, create brief.txt in the workspace and ask the agent to write a migration plan to plan.md.
  5. Check that the turn completed, retrieve any files you need, then shut down the Devbox and delete the session.

Use bounded setup and execution timeouts, plus a Devbox lifetime limit as a fallback if your application exits unexpectedly. Keep the session and Devbox alive if you need follow-up turns. Use one provisioning owner per session; do not attach a provisioning webhook handler to sessions your application manages directly.

References