Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

docs(sandbox): add OpenAI Agents API Fleet integration (#3745)

Francesco Bonacci143ea50755ba
diff --git a/docs/content/docs/how-to-guides/sandbox/meta.json b/docs/content/docs/how-to-guides/sandbox/meta.json
index 64f1481b0e..8e80aacb6a 100644
--- a/docs/content/docs/how-to-guides/sandbox/meta.json
+++ b/docs/content/docs/how-to-guides/sandbox/meta.json
@@ -8,6 +8,7 @@
"create-pool-with-python",
"create-pool-with-typescript",
"run-cursor-cloud-agent-on-fleet",
+ "run-openai-agents-api-on-cloud-fleet",
"expire-pools-and-claims",
"troubleshoot-fleet-pools",
"run-openclaw-on-cloud-fleet",
diff --git a/docs/content/docs/how-to-guides/sandbox/run-openai-agents-api-on-cloud-fleet.mdx b/docs/content/docs/how-to-guides/sandbox/run-openai-agents-api-on-cloud-fleet.mdx
new file mode 100644
index 0000000000..b9b39ac05d
--- /dev/null
+++ b/docs/content/docs/how-to-guides/sandbox/run-openai-agents-api-on-cloud-fleet.mdx
@@ -0,0 +1,239 @@
+---
+title: Run OpenAI Agents API on Cua Cloud Fleet
+description: Connect an OpenAI Agents API self-hosted environment to a claimed Cua Cloud Fleet Linux desktop.
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Use this guide to run an OpenAI Agents API `self_hosted` environment inside a
+Cua Cloud Fleet VM. A Python controller creates a session, claims a Linux
+desktop, starts `codex exec-server` in the VM, and gives the agent access to
+Cua Driver through a local stdio MCP server.
+
+```text
+OpenAI Agents API control plane
+ ^
+ | outbound executor connection
+ |
+codex exec-server in a claimed Cua Fleet VM
+ |
+ +-- shell and workspace files
+ +-- Cua Driver stdio MCP
+ +-- XFCE/X11 desktop and browser
+```
+
+<Callout type="warn">
+ This is an application-managed integration, not a built-in OpenAI sandbox provider. Your
+ controller owns the mapping between each OpenAI session and Fleet claim, and it must clean up
+ both resources. Deleting an OpenAI session does not release Fleet compute.
+</Callout>
+
+## Prerequisites
+
+You need:
+
+- Python `>=3.11,<3.14` and [`uv`](https://docs.astral.sh/uv/);
+- Cua Fleet credentials that can create pools and claims;
+- an OpenAI application API key with `api.agents.read`, `api.agents.write`, and
+ `api.responses.write` permissions; and
+- a separate OpenAI environment key with only
+ `api.agents.environments.connect` permission.
+
+Create the restricted key in the OpenAI Platform
+[`Agents` environment-key view](https://platform.openai.com/agents?tab=environments&environment_view=keys).
+OpenAI requires the application and environment keys to belong to the same
+organization, project, and user or service account.
+
+The controller uses this immutable public Linux desktop image:
+
+```text
+public.ecr.aws/k5j5w0x5/cua-ubuntu-24.04@sha256:80fff8a40f217a460cef7a60161adb3899eabd02c3451f18926b84d1f81b8da2
+```
+
+It boots Ubuntu 24.04 with XFCE on X11 and exposes the Cua computer server as
+the Fleet `server` service on port `8000`.
+
+## Configure credentials
+
+Authenticate to Cua Fleet with a workload token:
+
+```bash
+export FLEETS_TOKEN="<your-cua-access-token>"
+```
+
+Or use Cua OAuth client credentials:
+
+```bash
+export CUA_CLIENT_ID="<your-cua-client-id>"
+export CUA_CLIENT_SECRET="<your-cua-client-secret>"
+```
+
+Export the two OpenAI keys separately:
+
+```bash
+export OPENAI_API_KEY="<your-application-api-key>"
+export CODEX_API_KEY="<your-restricted-environment-key>"
+```
+
+The controller keeps `OPENAI_API_KEY` outside the VM. It transfers only
+`CODEX_API_KEY` through the Fleet file API to a mode-`600` temporary file,
+starts the executor, and removes the file immediately. Agent-generated code
+can still read the executor process environment. The restricted key limits the
+impact of that access because it cannot create sessions or make model calls.
+
+Keep all credentials in environment variables or a secret manager. Do not
+store them in the image or commit them to source control.
+
+## Run the controller
+
+Download the verified controller:
+
+```bash
+curl -fsSLO https://cua.ai/scripts/openai-agents-fleet/run_openai_agents_fleet.py
+```
+
+Run the controller. It generates a unique disposable pool name for each run:
+
+```bash
+uv run run_openai_agents_fleet.py
+```
+
+The script performs a complete validation sequence:
+
+1. It creates a Fleet pool and claim with two-hour and one-hour TTL fallbacks.
+2. It installs pinned Cua Driver and Codex CLI versions in the disposable VM.
+3. It creates an OpenAI `self_hosted` session and starts a detached executor.
+4. In the first turn, it creates and reads back the artifact, then uses Cua
+ Driver MCP to launch an XFCE terminal, take two exact window snapshots, and
+ click **File** and **Close Window** with fresh snapshot-bound targets.
+5. It stops the executor, observes the disconnect, submits a second turn, and
+ observes OpenAI request the original environment connection.
+6. It reconnects the same environment ID and reads the same artifact again.
+7. It retrieves `/workspace/outputs/openai-cua-fleet-e2e.txt` through the Fleet
+ file API before deleting the OpenAI session, claim, and pool.
+
+A passing run ends with output similar to this:
+
+```text
+Executor connection: PASS
+Cua Driver MCP evidence: PASS
+Executor disconnect observation: PASS
+Same-environment reconnect: PASS
+Artifact retrieval: PASS (.../openai-cua-fleet-e2e.txt)
+OpenAI session, Fleet claim, and Fleet pool cleanup: PASS
+```
+
+Open the downloaded artifact and confirm that it contains:
+
+```text
+OPENAI AGENTS API ON CUA CLOUD FLEET PASSED
+```
+
+## Understand the lifecycle
+
+The controller uses one Fleet claim for one OpenAI environment ID. Reconnecting
+starts a new executor process with the original `session.environment.id` and
+`session.environment.remote_url`; it does not create a second claim.
+
+```text
+OpenAI session/environment ID
+ |
+ | stored application mapping
+ v
+Cua Fleet pool + claim
+ |
+ +-- detached executor PID and logs
+ +-- workspace files
+ +-- output files retrieved before release
+```
+
+An Agents API event stream reports connection changes and turn outcomes. The
+controller waits for `agent.session.environment.connected` before submitting
+the first turn and checks each root turn for `completed`, `failed`, or
+`cancelled`. After the intentional disconnect, it submits the second turn and
+waits for `agent.session.requires_action` with an `environment_connection`
+action before restarting the executor. It does not treat an idle event as
+success.
+
+The example deletes its pool after every run. For a service, keep a reusable
+pool and create one claim per active session. Persist the session-to-claim
+mapping in a transactional store, make environment startup idempotent, and
+reconcile orphaned resources after controller restarts.
+
+## Retrieve files before cleanup
+
+The OpenAI Artifacts API does not publish files from `self_hosted`
+environments. Ask the agent to write outputs to known paths, then use
+`sandbox.files.read_bytes()` or `sandbox.files.download()` while the Fleet
+claim is still active.
+
+Retrieve every required output before either of these actions:
+
+- releasing the Fleet claim, which returns the VM to its pool and resets its
+ disposable disk overlay; or
+- deleting the pool, which removes its warm capacity and namespace.
+
+## Production hardening
+
+Before using this integration for production workloads:
+
+- publish a private, pinned image with Cua Driver and Codex CLI preinstalled;
+- run the executor as a dedicated non-root user;
+- store the environment key in a workload secret service and inject it only
+ for executor startup;
+- restrict egress to `api.openai.com`,
+ `codex-cloud-environments.chatgpt.com`, and workload-specific destinations;
+- keep exactly one controller responsible for each session-to-claim mapping;
+- supervise executor health separately from the OpenAI event stream;
+- coordinate shutdown with incoming turns and recheck session state before
+ releasing compute;
+- retrieve required files before release and define retention for logs and
+ screenshots; and
+- test cancellation, process crashes, controller restarts, connection expiry,
+ and cleanup failures.
+
+OpenAI can send agent-required content through its control plane, including
+prompts, file contents, shell output, MCP tool results, and screenshots.
+Running the executor on Fleet keeps the execution environment in the claimed
+VM; it does not make the OpenAI agent harness or model inference self-hosted.
+
+## Scale from zero
+
+The example provisions before it submits work. A demand-driven integration can
+instead subscribe to `agent.session.action_required` webhooks whose required
+action is `environment_connection`.
+
+A production webhook controller must:
+
+1. Verify the OpenAI webhook signature and durably queue the event.
+2. Retrieve the session and confirm that it still needs an environment.
+3. Atomically resolve or create the session-to-claim mapping.
+4. Claim Fleet capacity and start or reconnect the executor.
+5. Release compute for sessions that remain failed.
+
+Return a successful webhook response only after the event is durably queued.
+Do not start a second claim for duplicate deliveries. OpenAI waits up to five
+minutes for an input-time environment connection, so size Fleet warm capacity
+and controller timeouts accordingly.
+
+## Troubleshooting
+
+| Symptom | Check |
+| --- | --- |
+| Executor exits with `missing required scope api.agents.environments.connect` | Use a separate environment key from the OpenAI Agents environment-key view, not the application key |
+| Session remains pending | Check the executor log in `/run/cua-agents/executor.log`, both allowed OpenAI hosts, and the environment ID and remote URL mapping |
+| Required MCP initialization fails | Confirm `/root/.local/bin/cua-driver` exists, `DISPLAY` points to the XFCE X11 session and appears in `transport.env_vars`, and the stdio MCP `cwd` is `/workspace` |
+| Fleet claim never becomes ready | Verify Cua credentials, pool-name uniqueness, image access, and the `server` service on port `8000` |
+| Reconnect creates an empty workspace | Reconnect the original claim; a replacement VM does not restore files unless you use provider storage or snapshots |
+| Output is missing after cleanup | Self-hosted files must be retrieved through Fleet before the claim is released |
+| Compute remains after deleting the OpenAI session | Expected: OpenAI session deletion and Fleet claim release are separate operations |
+
+## Related documentation
+
+- [Create a sandbox pool with Python](/how-to-guides/sandbox/create-pool-with-python)
+- [Pass secrets into a sandbox](/how-to-guides/sandbox/secrets)
+- [Run sandboxes in parallel](/how-to-guides/sandbox/scale-out)
+- [OpenAI self-hosted sandboxes](https://developers.openai.com/api/docs/guides/agents-api/environments/self-hosted)
+- [OpenAI sandbox lifecycle](https://developers.openai.com/api/docs/guides/agents-api/environments/lifecycle)
+- [OpenAI MCP connections](https://developers.openai.com/api/docs/guides/agents-api/tools/mcp)
+- [OpenAI files and artifacts](https://developers.openai.com/api/docs/guides/agents-api/environments/files)
diff --git a/docs/public/scripts/openai-agents-fleet/run_openai_agents_fleet.py b/docs/public/scripts/openai-agents-fleet/run_openai_agents_fleet.py
new file mode 100644
index 0000000000..ca33346af8
--- /dev/null
+++ b/docs/public/scripts/openai-agents-fleet/run_openai_agents_fleet.py
@@ -0,0 +1,724 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11,<3.14"
+# dependencies = [
+# "cua-sandbox==0.7.0",
+# "httpx>=0.27,<1",
+# ]
+# ///
+"""Run an OpenAI Agents API self-hosted session on Cua Cloud Fleet.
+
+The application API key remains on the controller. Only the restricted
+environment key is copied into the claimed VM, and its temporary file is
+removed as soon as the detached executor starts.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import os
+from pathlib import Path
+import secrets
+import shlex
+from typing import Any, AsyncIterator, Callable
+
+import httpx
+from cua_sandbox import Image, Pool
+
+
+AGENTS_BASE_URL = "https://api.openai.com/v1/agents/"
+AGENTS_BETA_HEADER = "agents=v1"
+IMAGE = (
+ "public.ecr.aws/k5j5w0x5/cua-ubuntu-24.04"
+ "@sha256:80fff8a40f217a460cef7a60161adb3899eabd02c3451f18926b84d1f81b8da2"
+)
+CODEX_VERSION = "0.155.0-alpha.3"
+CUA_DRIVER_VERSION = "0.27.0"
+ARTIFACT_PATH = "/workspace/outputs/openai-cua-fleet-e2e.txt"
+ARTIFACT_CONTENT = "OPENAI AGENTS API ON CUA CLOUD FLEET PASSED\n"
+RUNTIME_DIR = "/run/cua-agents"
+EXECUTOR_ENV_PATH = f"{RUNTIME_DIR}/executor.env"
+EXECUTOR_LAUNCHER_PATH = f"{RUNTIME_DIR}/launch-executor"
+EXECUTOR_LOG_PATH = f"{RUNTIME_DIR}/executor.log"
+EXECUTOR_PID_PATH = f"{RUNTIME_DIR}/executor.pid"
+MCP_AUDIT_PROXY_PATH = f"{RUNTIME_DIR}/mcp-audit-proxy.py"
+MCP_AUDIT_LOG_PATH = f"{RUNTIME_DIR}/mcp-tool-names.log"
+E2E_TERMINAL_PATH = f"{RUNTIME_DIR}/e2e-terminal"
+E2E_TARGET_PATH = f"{RUNTIME_DIR}/e2e-target"
+TERMINAL_TURN_EVENTS = {
+ "agent.session.turn.completed",
+ "agent.session.turn.failed",
+ "agent.session.turn.cancelled",
+}
+
+
+def required_env(name: str) -> str:
+ value = os.environ.get(name, "").strip()
+ if not value:
+ raise RuntimeError(f"Set {name} before running this controller")
+ return value
+
+
+def pool_name() -> str:
+ # This example deletes its pool. Never reconcile a caller's existing pool.
+ # Fleet appends an instance suffix and service name; leave room under 63 bytes.
+ return f"cua-openai-agents-{secrets.token_hex(12)}"
+
+
+def root_turn(event: dict[str, Any]) -> bool:
+ turn = event.get("turn")
+ return not isinstance(turn, dict) or turn.get("subagent_id") is None
+
+
+async def checked(sandbox: Any, command: str, timeout: int = 300) -> str:
+ result = await sandbox.shell.run(command, timeout=timeout)
+ if not result.success:
+ detail = result.stderr.strip() or result.stdout.strip() or "command failed"
+ raise RuntimeError(detail)
+ return result.stdout.strip()
+
+
+async def checked_read(
+ sandbox: Any,
+ command: str,
+ *,
+ timeout: int = 300,
+ attempts: int = 3,
+) -> str:
+ """Retry a read-only shell probe after transient Fleet transport failures."""
+ for attempt in range(1, attempts + 1):
+ try:
+ return await checked(sandbox, command, timeout=timeout)
+ except Exception:
+ if attempt == attempts:
+ raise
+ await asyncio.sleep(2)
+ raise AssertionError("unreachable")
+
+
+class AgentsClient:
+ """Small async client for the public Agents API beta HTTP contract."""
+
+ def __init__(self, api_key: str) -> None:
+ self._client = httpx.AsyncClient(
+ base_url=AGENTS_BASE_URL,
+ headers={
+ "Authorization": f"Bearer {api_key}",
+ "OpenAI-Beta": AGENTS_BETA_HEADER,
+ },
+ timeout=httpx.Timeout(60, read=None),
+ follow_redirects=False,
+ )
+
+ async def close(self) -> None:
+ await self._client.aclose()
+
+ async def request(
+ self,
+ method: str,
+ path: str,
+ *,
+ payload: dict[str, Any] | None = None,
+ params: dict[str, Any] | None = None,
+ ) -> dict[str, Any]:
+ attempts = 3 if method == "GET" else 1
+ for attempt in range(1, attempts + 1):
+ response = await self._client.request(
+ method, path, json=payload, params=params
+ )
+ if response.status_code < 500 or attempt == attempts:
+ response.raise_for_status()
+ if not response.content:
+ return {}
+ return response.json()
+ await asyncio.sleep(2)
+ raise AssertionError("unreachable")
+
+ async def create_session(self) -> dict[str, Any]:
+ return await self.request(
+ "POST",
+ "sessions",
+ payload={
+ "agent": {
+ "model": "gpt-6-astra",
+ "instructions": (
+ "Work carefully and report only behavior you observed. When a "
+ "desktop check is requested, you must use the named cua_driver MCP "
+ "tools for inspection and interaction; never substitute shell UI "
+ "automation."
+ ),
+ "tools": [
+ {
+ "type": "mcp",
+ "server_label": "cua_driver",
+ "transport": {
+ "type": "stdio",
+ "command": "/usr/bin/python3",
+ "args": [
+ MCP_AUDIT_PROXY_PATH,
+ "/root/.local/bin/cua-driver",
+ ],
+ "cwd": "/workspace",
+ "env_vars": [
+ "DISPLAY",
+ "CUA_DRIVER_PERMISSION_MODE",
+ "CUA_DRIVER_DANGEROUSLY_BYPASS_APPROVALS",
+ ],
+ },
+ "allowed_tools": [
+ "launch_app",
+ "get_window_state",
+ "click",
+ "verify_state",
+ ],
+ "required": True,
+ }
+ ],
+ },
+ "environment": {
+ "type": "self_hosted",
+ "workspace_directory": "/workspace",
+ },
+ },
+ )
+
+ async def delete_session(self, session_id: str) -> None:
+ for attempt in range(1, 11):
+ response = await self._client.delete(f"sessions/{session_id}")
+ if response.status_code in {200, 202, 204, 404}:
+ return
+ if response.status_code == 409 and attempt < 10:
+ await asyncio.sleep(2)
+ continue
+ response.raise_for_status()
+ raise AssertionError("unreachable")
+
+ async def retrieve_session(self, session_id: str) -> dict[str, Any]:
+ return await self.request("GET", f"sessions/{session_id}")
+
+ async def send_message(self, session_id: str, text: str) -> None:
+ await self.request(
+ "POST",
+ f"sessions/{session_id}/events",
+ payload={
+ "events": [
+ {
+ "type": "agent.session.input.message",
+ "input": [
+ {
+ "role": "user",
+ "content": [{"type": "input_text", "text": text}],
+ }
+ ],
+ }
+ ]
+ },
+ )
+
+ async def list_items(self, session_id: str) -> dict[str, Any]:
+ items: list[dict[str, Any]] = []
+ after: str | None = None
+ for _ in range(20):
+ params: dict[str, Any] = {"order": "asc", "limit": 100}
+ if after is not None:
+ params["after"] = after
+ page = await self.request(
+ "GET",
+ f"sessions/{session_id}/items",
+ params=params,
+ )
+ page_items = page.get("data", [])
+ items.extend(page_items)
+ if not page.get("has_more"):
+ return {"data": items}
+ after = page.get("last_id") or (
+ page_items[-1].get("id") if page_items else None
+ )
+ if not after:
+ raise RuntimeError("Items page was truncated without a continuation cursor")
+ raise RuntimeError("Items pagination exceeded 20 pages")
+
+ @contextlib.asynccontextmanager
+ async def event_lines(self, session_id: str) -> AsyncIterator[AsyncIterator[str]]:
+ async with self._client.stream(
+ "GET",
+ f"sessions/{session_id}/events",
+ params={"stream": "true"},
+ headers={"Accept": "text/event-stream"},
+ ) as response:
+ response.raise_for_status()
+ yield response.aiter_lines()
+
+
+class EventMonitor:
+ def __init__(self, lines: AsyncIterator[str]) -> None:
+ self._lines = lines
+ self._events: asyncio.Queue[dict[str, Any] | BaseException] = asyncio.Queue()
+ self.observed: list[dict[str, Any]] = []
+ self._task = asyncio.create_task(self._consume())
+
+ async def _consume(self) -> None:
+ data: list[str] = []
+ try:
+ async for line in self._lines:
+ if line == "":
+ if data:
+ raw = "\n".join(data)
+ data.clear()
+ if raw == "[DONE]":
+ continue
+ event = json.loads(raw)
+ self.observed.append(event)
+ await self._events.put(event)
+ continue
+ if line.startswith("data:"):
+ data.append(line[5:].lstrip())
+ except BaseException as error:
+ await self._events.put(error)
+
+ async def wait_for(
+ self,
+ predicate: Callable[[dict[str, Any]], bool],
+ *,
+ timeout: float,
+ ) -> dict[str, Any]:
+ async with asyncio.timeout(timeout):
+ while True:
+ item = await self._events.get()
+ if isinstance(item, BaseException):
+ raise item
+ if predicate(item):
+ return item
+
+ async def wait_for_type(self, event_type: str, *, timeout: float = 180) -> dict[str, Any]:
+ return await self.wait_for(lambda event: event.get("type") == event_type, timeout=timeout)
+
+ async def wait_for_root_turn(self, *, timeout: float = 900) -> dict[str, Any]:
+ return await self.wait_for(
+ lambda event: event.get("type") in TERMINAL_TURN_EVENTS and root_turn(event),
+ timeout=timeout,
+ )
+
+ async def close(self) -> None:
+ self._task.cancel()
+ with contextlib.suppress(asyncio.CancelledError):
+ await self._task
+
+
+def mcp_audit_proxy() -> str:
+ return f'''#!/usr/bin/python3
+import json
+import subprocess
+import sys
+import threading
+
+child = subprocess.Popen(
+ [sys.argv[1], "mcp"],
+ stdin=subprocess.PIPE,
+ stdout=subprocess.PIPE,
+ stderr=sys.stderr.buffer,
+)
+
+
+def relay_stdout():
+ while chunk := child.stdout.read1(65536):
+ sys.stdout.buffer.write(chunk)
+ sys.stdout.buffer.flush()
+
+
+threading.Thread(target=relay_stdout, daemon=True).start()
+for line in sys.stdin.buffer:
+ try:
+ message = json.loads(line)
+ if message.get("method") == "tools/call":
+ name = message.get("params", {{}}).get("name")
+ if isinstance(name, str):
+ with open({MCP_AUDIT_LOG_PATH!r}, "a", encoding="utf-8") as audit:
+ audit.write(name + "\\n")
+ except (json.JSONDecodeError, AttributeError):
+ pass
+ child.stdin.write(line)
+ child.stdin.flush()
+
+child.stdin.close()
+raise SystemExit(child.wait())
+'''
+
+
+def e2e_terminal_launcher() -> str:
+ """Launch a synthetic GTK terminal and publish its proven PID/XID pair."""
+ return f'''#!/bin/bash
+set -euo pipefail
+rm -f {shlex.quote(E2E_TARGET_PATH)}
+xfce4-terminal --disable-server --title='OPENAI CUA FLEET E2E' --hold \\
+ --command="bash -lc 'printf \\\"OPENAI CUA FLEET E2E\\\\n\\\"; sleep 3600'" &
+terminal_pid=$!
+window_id=''
+for _attempt in $(seq 1 50); do
+ window_id=$(xwininfo -root -tree 2>/dev/null | awk '/"OPENAI CUA FLEET E2E"/ && /xfce4-terminal/ {{print $1; exit}}')
+ test -n "$window_id" && break
+ sleep 0.1
+done
+test -n "$window_id"
+window_pid=$(xprop -id "$window_id" _NET_WM_PID | awk '{{print $3}}')
+test "$window_pid" -gt 0
+printf '%s %s\n' "$window_pid" "$((window_id))" > {shlex.quote(E2E_TARGET_PATH)}
+wait "$terminal_pid"
+'''
+
+
+async def install_runtime(sandbox: Any) -> str:
+ await checked(sandbox, "mkdir -p /workspace /workspace/outputs /run/cua-agents")
+ await checked(sandbox, "chmod 700 /run/cua-agents")
+ await checked(
+ sandbox,
+ "curl -fsSL https://cua.ai/driver/install.sh -o /tmp/cua-driver-install.sh",
+ )
+ await checked(
+ sandbox,
+ f"CUA_DRIVER_RS_VERSION={CUA_DRIVER_VERSION} "
+ "bash /tmp/cua-driver-install.sh --no-modify-path",
+ timeout=600,
+ )
+ await checked(
+ sandbox,
+ f"npm install --global @openai/codex@{CODEX_VERSION}",
+ timeout=600,
+ )
+ await checked(sandbox, "/root/.local/bin/cua-driver --version")
+ await sandbox.files.write_bytes(MCP_AUDIT_PROXY_PATH, mcp_audit_proxy().encode())
+ await sandbox.files.write_bytes(
+ E2E_TERMINAL_PATH,
+ e2e_terminal_launcher().encode(),
+ )
+ await checked(sandbox, f"chmod 700 {shlex.quote(MCP_AUDIT_PROXY_PATH)}")
+ await checked(sandbox, f"chmod 700 {shlex.quote(E2E_TERMINAL_PATH)}")
+ codex_path = await checked(sandbox, "command -v codex")
+ if not codex_path.startswith("/"):
+ raise RuntimeError("Codex CLI did not resolve to an absolute path")
+ return codex_path
+
+
+def executor_launcher(
+ *, codex_path: str, remote_url: str, environment_id: str, display: str
+) -> str:
+ return f"""#!/bin/bash
+set -euo pipefail
+umask 077
+set -a
+. {shlex.quote(EXECUTOR_ENV_PATH)}
+set +a
+rm -f {shlex.quote(EXECUTOR_ENV_PATH)}
+echo $$ > {shlex.quote(EXECUTOR_PID_PATH)}
+export DISPLAY={shlex.quote(display)}
+export PATH=/root/.local/bin:/usr/local/bin:/usr/bin:/bin
+export CUA_DRIVER_PERMISSION_MODE=unrestricted
+export CUA_DRIVER_DANGEROUSLY_BYPASS_APPROVALS=1
+exec {shlex.quote(codex_path)} exec-server \\
+ --remote {shlex.quote(remote_url)} \\
+ --environment-id {shlex.quote(environment_id)}
+"""
+
+
+async def start_executor(
+ sandbox: Any,
+ *,
+ environment_key: str,
+ launcher: str,
+) -> int:
+ # The file API keeps the key out of shell arguments and controller logs.
+ await sandbox.files.write_bytes(
+ EXECUTOR_ENV_PATH,
+ f"CODEX_API_KEY={shlex.quote(environment_key)}\n".encode(),
+ )
+ await sandbox.files.write_bytes(EXECUTOR_LAUNCHER_PATH, launcher.encode())
+ await checked(
+ sandbox,
+ f"chmod 600 {shlex.quote(EXECUTOR_ENV_PATH)} && "
+ f"chmod 700 {shlex.quote(EXECUTOR_LAUNCHER_PATH)}",
+ )
+ launch_result = await sandbox.shell.run(
+ f"exec /bin/bash {shlex.quote(EXECUTOR_LAUNCHER_PATH)} "
+ f"> {shlex.quote(EXECUTOR_LOG_PATH)} 2>&1",
+ background=True,
+ )
+ if not launch_result.success:
+ raise RuntimeError(launch_result.stderr.strip() or "executor launch failed")
+ status_command = (
+ f"pid=$(cat {shlex.quote(EXECUTOR_PID_PATH)} 2>/dev/null || true); "
+ "if test -z \"$pid\"; then echo NO_PID; "
+ "elif ! kill -0 \"$pid\" 2>/dev/null; then echo EXITED; "
+ f"elif test -e {shlex.quote(EXECUTOR_ENV_PATH)}; then echo STARTING; "
+ "else echo READY:$pid; fi"
+ )
+ last_status = "NO_RESPONSE"
+ ready_checks = 0
+ for _ in range(30):
+ try:
+ last_status = await checked_read(
+ sandbox,
+ status_command,
+ timeout=10,
+ attempts=2,
+ )
+ except Exception:
+ last_status = "TRANSPORT_ERROR"
+ if last_status.startswith("READY:"):
+ raw_pid = last_status.removeprefix("READY:")
+ if not raw_pid.isdigit():
+ raise RuntimeError("Executor did not publish a numeric process ID")
+ ready_checks += 1
+ if ready_checks >= 3:
+ return int(raw_pid)
+ else:
+ ready_checks = 0
+ if last_status == "EXITED":
+ break
+ await asyncio.sleep(1)
+
+ log_tail = await checked_read(
+ sandbox,
+ f"tail -n 60 {shlex.quote(EXECUTOR_LOG_PATH)} 2>/dev/null | "
+ "sed -E 's/sk-[A-Za-z0-9_-]+/[REDACTED]/g'",
+ timeout=10,
+ )
+ raise RuntimeError(
+ f"Executor did not become ready (status {last_status}); "
+ f"sanitized log tail:\n{log_tail or '(empty)'}"
+ )
+
+
+async def stop_executor(sandbox: Any) -> None:
+ await checked(
+ sandbox,
+ f"if test -f {shlex.quote(EXECUTOR_PID_PATH)}; then "
+ f"pid=$(cat {shlex.quote(EXECUTOR_PID_PATH)}); "
+ "kill \"$pid\" 2>/dev/null || true; "
+ "for attempt in $(seq 1 30); do "
+ "kill -0 \"$pid\" 2>/dev/null || exit 0; sleep 1; done; "
+ "kill -KILL \"$pid\" 2>/dev/null || true; fi",
+ timeout=45,
+ )
+
+
+async def verify_desktop_evidence(sandbox: Any) -> None:
+ audit_names = (
+ (await sandbox.files.read_bytes(MCP_AUDIT_LOG_PATH)).decode().splitlines()
+ )
+ missing = [
+ name for name in ("launch_app", "click") if name not in audit_names
+ ]
+ if audit_names.count("get_window_state") < 2:
+ missing.append("two get_window_state calls")
+ if audit_names.count("click") < 2:
+ missing.append("two click calls")
+ if missing:
+ raise RuntimeError(
+ "MCP audit lacks required Cua Driver evidence: " + ", ".join(missing)
+ )
+ terminal_state = await checked_read(
+ sandbox,
+ f"read -r pid window_id < {shlex.quote(E2E_TARGET_PATH)}; "
+ "for attempt in $(seq 1 30); do "
+ "kill -0 \"$pid\" 2>/dev/null || { echo CLOSED; exit 0; }; "
+ "sleep 0.2; done; echo OPEN",
+ )
+ if terminal_state != "CLOSED":
+ raise RuntimeError("Cua Driver clicks did not close the terminal")
+
+
+async def cleanup_resources(
+ agents: AgentsClient,
+ *,
+ session: dict[str, Any] | None,
+ pool: Pool | None,
+) -> list[Exception]:
+ errors: list[Exception] = []
+ if session is not None:
+ try:
+ await agents.delete_session(session["id"])
+ except Exception as error:
+ errors.append(error)
+ try:
+ await agents.close()
+ except Exception as error:
+ errors.append(error)
+ if pool is not None:
+ try:
+ await pool.delete()
+ except Exception as error:
+ errors.append(error)
+ return errors
+
+
+async def main() -> None:
+ application_key = required_env("OPENAI_API_KEY")
+ environment_key = required_env("CODEX_API_KEY")
+ selected_pool_name = pool_name()
+ output_path = Path(
+ os.environ.get("CUA_ARTIFACT_DESTINATION", "openai-cua-fleet-e2e.txt")
+ ).resolve()
+ agents = AgentsClient(application_key)
+ pool: Pool | None = None
+ session: dict[str, Any] | None = None
+ sandbox: Any = None
+ executor_running = False
+ run_error: Exception | None = None
+
+ try:
+ pool = await Pool.apply(
+ Image.from_registry(IMAGE, os_type="linux", kind="vm"),
+ name=selected_pool_name,
+ replicas=1,
+ cpu=4,
+ memory_mb=8192,
+ services={"server": 8000},
+ ttl_seconds_after_created=7200,
+ )
+ async with pool.claim(
+ name=f"session-{secrets.token_hex(4)}",
+ service="server",
+ time_to_start=1800,
+ ttl_seconds_after_created=3600,
+ ) as sandbox:
+ print(f"Cua pool: {sandbox.pool_name}")
+ print(f"Cua claim: {sandbox.claim_name}")
+ codex_path = await install_runtime(sandbox)
+ display = (await checked(sandbox, "printf %s \"${DISPLAY:-:1}\"")).strip() or ":1"
+
+ session = await agents.create_session()
+ session_id = session["id"]
+ environment = session["environment"]
+ launcher = executor_launcher(
+ codex_path=codex_path,
+ remote_url=environment["remote_url"],
+ environment_id=environment["id"],
+ display=display,
+ )
+
+ async with agents.event_lines(session_id) as lines:
+ monitor = EventMonitor(lines)
+ try:
+ await start_executor(
+ sandbox,
+ environment_key=environment_key,
+ launcher=launcher,
+ )
+ executor_running = True
+ await monitor.wait_for_type("agent.session.environment.connected")
+ print("Executor connection: PASS")
+
+ await agents.send_message(
+ session_id,
+ f"Write exactly {ARTIFACT_CONTENT.strip()!r} followed by a newline "
+ f"to {ARTIFACT_PATH}. Read the file back and report the exact "
+ "contents. Then perform this desktop check with the cua_driver MCP "
+ f"tools. (1) Call `launch_app` with name `/bin/bash` and "
+ f"additional_arguments [`{E2E_TERMINAL_PATH}`]. (2) Use the shell to "
+ f"wait up to 10 seconds for `{E2E_TARGET_PATH}` to become non-empty, "
+ "then read its two integers; they are the terminal's owner PID and "
+ "window ID. This read is discovery only, not UI automation. (3) Call "
+ "`get_window_state` for that exact PID and window ID. (4) Call `click` "
+ "on the `File` menu using the element token from that snapshot, not "
+ "coordinates. (5) Call `get_window_state` again, then call `click` on "
+ "`Close Terminal` or `Close Window` using the fresh element token from "
+ "the second snapshot. (6) Use the shell only to verify that the "
+ "published terminal PID is no longer running. Do not report success "
+ "unless every step completed.",
+ )
+ first_turn = await monitor.wait_for_root_turn()
+ if first_turn["type"] != "agent.session.turn.completed":
+ raise RuntimeError(
+ "First turn did not complete: "
+ + json.dumps(first_turn, sort_keys=True)
+ )
+ initial_artifact = await sandbox.files.read_bytes(ARTIFACT_PATH)
+ if initial_artifact != ARTIFACT_CONTENT.encode():
+ raise RuntimeError(
+ "Agent-created Fleet artifact content did not match"
+ )
+ await verify_desktop_evidence(sandbox)
+ print("Cua Driver MCP evidence: PASS")
+
+ await stop_executor(sandbox)
+ executor_running = False
+ await monitor.wait_for_type("agent.session.environment.disconnected")
+ print("Executor disconnect observation: PASS")
+
+ second_submission = asyncio.create_task(
+ agents.send_message(
+ session_id,
+ f"Read {ARTIFACT_PATH} and report its exact contents, including "
+ "whether it ends with a newline.",
+ )
+ )
+ try:
+ await monitor.wait_for_type(
+ "agent.session.requires_action", timeout=60
+ )
+ pending_session = await agents.retrieve_session(session_id)
+ required_actions = pending_session.get("required_actions", [])
+ if not any(
+ action.get("type") == "environment_connection"
+ and action.get("environment_id") == environment["id"]
+ for action in required_actions
+ if isinstance(action, dict)
+ ):
+ raise RuntimeError(
+ "Session did not request the original environment connection"
+ )
+ await start_executor(
+ sandbox,
+ environment_key=environment_key,
+ launcher=launcher,
+ )
+ executor_running = True
+ await monitor.wait_for_type("agent.session.environment.connected")
+ print("Same-environment reconnect: PASS")
+ await second_submission
+ finally:
+ if not second_submission.done():
+ second_submission.cancel()
+ with contextlib.suppress(asyncio.CancelledError):
+ await second_submission
+
+ second_turn = await monitor.wait_for_root_turn()
+ if second_turn["type"] != "agent.session.turn.completed":
+ raise RuntimeError(
+ "Second turn did not complete: "
+ + json.dumps(second_turn, sort_keys=True)
+ )
+
+ await agents.list_items(session_id)
+ artifact = await sandbox.files.read_bytes(ARTIFACT_PATH)
+ if artifact != ARTIFACT_CONTENT.encode():
+ raise RuntimeError("Retrieved Fleet artifact content did not match")
+ output_path.write_bytes(artifact)
+ print(f"Artifact retrieval: PASS ({output_path})")
+ finally:
+ await monitor.close()
+ if executor_running:
+ await stop_executor(sandbox)
+ executor_running = False
+ except Exception as error:
+ run_error = error
+ finally:
+ cleanup_errors = await cleanup_resources(agents, session=session, pool=pool)
+
+ if run_error is not None:
+ if cleanup_errors:
+ raise ExceptionGroup(
+ "Controller run and cleanup both failed",
+ [run_error, *cleanup_errors],
+ )
+ raise run_error
+ if cleanup_errors:
+ raise ExceptionGroup("Resource cleanup failed", cleanup_errors)
+
+ print("OpenAI session, Fleet claim, and Fleet pool cleanup: PASS")
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/docs/scripts/tests/test_openai_agents_fleet_example.py b/docs/scripts/tests/test_openai_agents_fleet_example.py
new file mode 100644
index 0000000000..d9ef437eea
--- /dev/null
+++ b/docs/scripts/tests/test_openai_agents_fleet_example.py
@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import ast
+import os
+from pathlib import Path
+import secrets
+from unittest.mock import patch
+
+
+DOCS_ROOT = Path(__file__).resolve().parents[2]
+SCRIPT = (
+ DOCS_ROOT
+ / "public/scripts/openai-agents-fleet/run_openai_agents_fleet.py"
+)
+GUIDE = (
+ DOCS_ROOT
+ / "content/docs/how-to-guides/sandbox/run-openai-agents-api-on-cloud-fleet.mdx"
+)
+META = DOCS_ROOT / "content/docs/how-to-guides/sandbox/meta.json"
+
+
+def test_disposable_pool_name_ignores_existing_pool_override() -> None:
+ tree = ast.parse(SCRIPT.read_text())
+ function = next(node for node in tree.body if isinstance(node, ast.FunctionDef)
+ and node.name == "pool_name")
+ namespace = {"os": os, "secrets": secrets}
+ exec(compile(ast.Module(body=[function], type_ignores=[]), str(SCRIPT), "exec"), namespace)
+ with patch.dict(os.environ, {"CUA_POOL_NAME": "existing-production-pool"}):
+ first = namespace["pool_name"]()
+ second = namespace["pool_name"]()
+ assert first != second
+ assert first.startswith("cua-openai-agents-")
+ assert len(first.removeprefix("cua-openai-agents-")) == 24
+ assert len(f"{first}-a84951d4-server".encode()) <= 63
+
+
+def test_controller_is_valid_python() -> None:
+ source = SCRIPT.read_text()
+ compile(source, str(SCRIPT), "exec")
+ ast.parse(source)
+
+
+def test_controller_keeps_application_key_outside_the_sandbox() -> None:
+ source = SCRIPT.read_text()
+ assert 'application_key = required_env("OPENAI_API_KEY")' in source
+ assert 'environment_key = required_env("CODEX_API_KEY")' in source
+ assert 'f"CODEX_API_KEY={shlex.quote(environment_key)}' in source
+ assert 'f"OPENAI_API_KEY={shlex.quote(' not in source
+ assert "await sandbox.files.write_bytes(" in source
+ assert "rm -f {shlex.quote(EXECUTOR_ENV_PATH)}" in source
+
+
+def test_controller_covers_reconnect_artifact_and_cleanup() -> None:
+ source = SCRIPT.read_text()
+ assert 'wait_for_type("agent.session.environment.disconnected")' in source
+ assert source.count("await start_executor(") >= 2
+ assert "await sandbox.files.read_bytes(ARTIFACT_PATH)" in source
+ assert "Agent-created Fleet artifact content did not match" in source
+ assert 'page.get("has_more")' in source
+ assert 'page.get("last_id")' in source
+ assert "await agents.delete_session" in source
+ assert "await pool.delete()" in source
+ assert 'response.status_code == 409' in source
+ assert "contextlib.suppress(Exception)" not in source
+ assert 'raise ExceptionGroup("Resource cleanup failed", cleanup_errors)' in source
+ assert 'last_status.startswith("READY:")' in source
+ assert "sanitized log tail" in source
+ assert "echo $$ > {shlex.quote(EXECUTOR_PID_PATH)}" in source
+ assert "background=True" in source
+
+
+def test_controller_registers_cua_driver_as_required_stdio_mcp() -> None:
+ source = SCRIPT.read_text()
+ assert '"server_label": "cua_driver"' in source
+ assert '"type": "stdio"' in source
+ assert '"command": "/usr/bin/python3"' in source
+ assert '"/root/.local/bin/cua-driver"' in source
+ assert '"cwd": "/workspace"' in source
+ assert '"CUA_DRIVER_PERMISSION_MODE"' in source
+ assert '"CUA_DRIVER_DANGEROUSLY_BYPASS_APPROVALS"' in source
+ assert '"DISPLAY"' in source
+ assert "export CUA_DRIVER_PERMISSION_MODE=unrestricted" in source
+ assert "export CUA_DRIVER_DANGEROUSLY_BYPASS_APPROVALS=1" in source
+ assert '"required": True' in source
+ assert '"allowed_tools": [' in source
+ assert '"launch_app"' in source
+ assert 'message.get("method") == "tools/call"' in source
+ assert "MCP_AUDIT_LOG_PATH" in source
+ assert 'terminal_state != "CLOSED"' in source
+ assert 'audit_names.count("get_window_state") < 2' in source
+ assert 'audit_names.count("click") < 2' in source
+
+
+def test_guide_links_the_download_and_navigation_entry() -> None:
+ guide = GUIDE.read_text()
+ meta = META.read_text()
+ assert "https://cua.ai/scripts/openai-agents-fleet/run_openai_agents_fleet.py" in guide
+ assert '"run-openai-agents-api-on-cloud-fleet"' in meta