Skip to content

ADR 0003: OpenAI Harness + Sandbox Adoption (Main SuperOptiX)

Status

Accepted - April 15, 2026

Context

OpenAI Agents SDK introduced a production runtime split (harness + sandbox) with SandboxAgent, manifest staging, and sandbox run config. This aligns with SuperOptiX's optimization-first model while reducing custom runtime glue code.

Decision

Adopt sandbox support in the main OpenAI framework path using official SDK APIs from openai-agents>=0.20,<0.21, without importing code from local protocol snapshots.

Scope Implemented

  1. SuperSpec additions:
  2. spec.openai_agent.sandbox.enabled
  3. spec.openai_agent.sandbox.client (unix_local or docker)
  4. spec.openai_agent.sandbox.docker_image
  5. spec.openai_agent.sandbox.workflow_name

  6. spec.openai_agent.sandbox.manifest (root, local_dirs, local_files, git_repos)

  7. Runtime:

  8. OpenAI runner helpers build SandboxAgent when sandbox is enabled.
  9. Runner helpers build RunConfig(sandbox=SandboxRunConfig(...)).

  10. Non-sandbox and low-version fallback remains supported with warnings.

  11. Templates:

  12. OpenAI minimal/optimized templates use sandbox-aware helper functions.

  13. Dependency floor:

  14. openai-agents>=0.20,<0.21 in OpenAI-related extras.

Best Path Forward (Phase 2+)

  1. Durable resume integration:
  2. Persist and reuse sandbox resume state across run/serve/optimize.

  3. Add explicit resume hooks in runtime and CLI entrypoints.

  4. Partner clients abstraction:

  5. Add provider adapters for Cloudflare, E2B, Modal, Daytona, etc.

  6. Keep a shared SuperOptiX sandbox client interface to avoid framework lock-in.

  7. Security policy layer:

  8. Add policy controls for tool approvals, mount permissions, and secret boundaries.

  9. Expose defaults in SuperSpec for enterprise-safe settings.

  10. Evaluation surface:

  11. Add BDD/eval cases for long-running sandbox jobs, crash/restart, and recovery behavior.
  12. Track durability metrics in observability traces.

Consequences

  • OpenAI path in main SuperOptiX now supports production-style sandbox execution.
  • Existing OpenAI agents remain backward-compatible when sandbox is disabled.
  • Further scalability and durability work should happen at runtime/CLI orchestration layers.