SpyBara
Go Premium

guides/agents-api/environments/providers/runloop.md 2026-09-10 18:01 UTC to 2026-09-11 20:00 UTC

This page contains 29 additions and 0 deletions.

2026
Fri 11 20:00 Mon 14 22:58 Sat 26 23:59

Runloop

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, OPENAI_API_KEY, and a separate restricted OPENAI_EXECUTOR_API_KEY. The OpenAI keys must have the same owner, organization, and project. Only the executor key enters the Devbox. See executor authentication.

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 restricted executor 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