Cloudflare | OpenAI API

Run sandbox tools in Cloudflare while OpenAI runs the agent and maintains session state. This guide uses webhook-managed provisioning with Cloudflare’s reference Worker.

How it works

Your application creates an Agents API session and sends input.
OpenAI sends session webhooks to a Worker in your Cloudflare account.
The Worker starts or reconnects a session-specific Container running codex exec-server. The executor connects outbound to OpenAI so the agent can run commands and work with files.

Your application uses the Agents API; the reference Worker manages sandbox provisioning. See Sandbox lifecycle for connection and recovery behavior.

Before you begin

You need a Cloudflare account with Containers access, an OpenAI application API key, and a separate restricted executor key. Follow executor authentication to configure the keys. Keep the application key outside the Container.

Create an agent and save its ID as OPENAI_AGENT_ID. Use the same agent ID in your application and the reference Worker.

Deploy the reference Worker

Cloudflare’s reference Worker includes the webhook handler, Container image, deployment configuration, and cleanup endpoint.

Generate a secret for the cleanup endpoint and save it as EXECUTOR_CLIENT_SECRET:

openssl rand -hex 32

Deploy the Worker in your Cloudflare account:

Deploy to Cloudflare

Enter these values when prompted:

Variable	Value
`OPENAI_API_KEY`	Key used by the Worker to retrieve session state
`OPENAI_EXECUTOR_API_KEY`	Restricted key passed to `codex exec-server`
`OPENAI_AGENT_ID`	Agent ID served by this Worker
`OPENAI_WEBHOOK_SECRET`	`pending-webhook-registration` for the first deployment
`EXECUTOR_CLIENT_SECRET`	Secret generated for cleanup

Save the deployed Worker URL as WORKER_URL.

Register the webhook

Follow webhook setup to register $WORKER_URL/webhook in your OpenAI project. Enable the events listed by Cloudflare’s reference integration:

agent.session.created
agent.session.action_required
agent.session.in_progress
agent.session.idle
agent.session.failed

Replace OPENAI_WEBHOOK_SECRET with the signing secret returned by OpenAI, then deploy the new Worker version. Check its configuration. These examples use standard HTTP clients to call the Worker:

Check Worker health

Python

1
2
3
4
5
6const response = await fetch(
  process.env.WORKER_URL.replace(/\/+$/, "") + "/health",
  { method: "GET" }
);
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
console.log(await response.text());

1
2
3
4
5
6
7import os
import urllib.request

url = os.environ["WORKER_URL"].rstrip("/") + "/health"
request = urllib.request.Request(url, method="GET")
with urllib.request.urlopen(request) as response:
    print(response.read().decode())

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import (
	"io"
	"net/http"
	"os"
	"strings"
)

endpoint := strings.TrimRight(os.Getenv("WORKER_URL"), "/") + "/health"
request, err := http.NewRequest("GET", endpoint, nil)
if err != nil {
	panic(err)
}
response, err := http.DefaultClient.Do(request)
if err != nil {
	panic(err)
}
defer response.Body.Close()
if response.StatusCode/100 != 2 {
	panic(response.Status)
}
if _, err := io.Copy(os.Stdout, response.Body); err != nil {
	panic(err)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String endpoint = System.getenv("WORKER_URL").replaceAll("/+$", "") + "/health";
var request =
    HttpRequest.newBuilder(URI.create(endpoint))
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() / 100 != 2)
  throw new IllegalStateException("Request failed: " + response.statusCode());
System.out.println(response.body());

1
2
3
4
5
6
7
8require "uri"
require "net/http"

uri = URI(ENV.fetch("WORKER_URL").sub(%r{/+\z}, "") + "/health")
request = Net::HTTP::Get.new(uri)
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
raise "Request failed: #{response.code}" unless response.is_a?(Net::HTTPSuccess)
puts response.body

1curl --fail-with-body "$WORKER_URL/health"

The response should contain both "configured": true and "webhook_configured": true.

An environment_connection required action is the signal to reconnect an offline executor. An idle event alone isn’t a safe shutdown signal; see lifecycle behavior.

Run a session

Follow the session steps with your application’s OPENAI_API_KEY and the same OPENAI_AGENT_ID configured in the Worker. Create a self-hosted session and ask the agent to write and read /workspace/hello.txt.

The Worker receives the session webhooks and connects the sandbox executor. Your application streams the agent’s output through the Agents API.

Save the session ID as SESSION_ID. To continue the conversation, open the session event stream before sending follow-up input. If the executor is offline, the new input requests an environment connection and waits for the Worker to reconnect it. Reconnection does not by itself restore files from a previous Container.

Run your application in a Worker

Cloudflare’s basic Worker application uses the @openai/agents-api TypeScript SDK to create sessions, send initial and follow-up input, and clean up resources. Its POST /demo endpoint runs the workflow.

This application also uses webhook-managed provisioning. Running your application in a Worker doesn’t mean it must provision the sandbox directly.

Cleanup

When the application no longer needs the sandbox, call the reference Worker’s authenticated cleanup endpoint:

Clean up the Worker sandbox

Python

1
2
3
4
5
6
7
8
9
10
11const response = await fetch(
  process.env.WORKER_URL.replace(/\/+$/, "") +
    "/executors/" +
    encodeURIComponent(process.env.SESSION_ID),
  {
    method: "DELETE",
    headers: { Authorization: `Bearer ${process.env.EXECUTOR_CLIENT_SECRET}` },
  }
);
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
console.log(await response.text());

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import os
from urllib.parse import quote
import urllib.request

url = (
    os.environ["WORKER_URL"].rstrip("/")
    + "/executors/"
    + quote(os.environ["SESSION_ID"], safe="")
)
request = urllib.request.Request(
    url,
    method="DELETE",
    headers={"Authorization": "Bearer " + os.environ["EXECUTOR_CLIENT_SECRET"]},
)
with urllib.request.urlopen(request) as response:
    print(response.read().decode())

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25import (
	"io"
	"net/http"
	"net/url"
	"os"
	"strings"
)

endpoint := strings.TrimRight(os.Getenv("WORKER_URL"), "/") + "/executors/" + url.PathEscape(os.Getenv("SESSION_ID"))
request, err := http.NewRequest("DELETE", endpoint, nil)
if err != nil {
	panic(err)
}
request.Header.Set("Authorization", "Bearer "+os.Getenv("EXECUTOR_CLIENT_SECRET"))
response, err := http.DefaultClient.Do(request)
if err != nil {
	panic(err)
}
defer response.Body.Close()
if response.StatusCode/100 != 2 {
	panic(response.Status)
}
if _, err := io.Copy(os.Stdout, response.Body); err != nil {
	panic(err)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;

String endpoint =
    System.getenv("WORKER_URL").replaceAll("/+$", "")
        + "/executors/"
        + URLEncoder.encode(System.getenv("SESSION_ID"), StandardCharsets.UTF_8)
            .replace("+", "%20");
var request =
    HttpRequest.newBuilder(URI.create(endpoint))
        .header("Authorization", "Bearer " + System.getenv("EXECUTOR_CLIENT_SECRET"))
        .method("DELETE", HttpRequest.BodyPublishers.noBody())
        .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() / 100 != 2)
  throw new IllegalStateException("Request failed: " + response.statusCode());
System.out.println(response.body());

1
2
3
4
5
6
7
8
9require "uri"
require "net/http"

uri = URI(ENV.fetch("WORKER_URL").sub(%r{/+\z}, "") + "/executors/" + URI.encode_www_form_component(ENV.fetch("SESSION_ID")).gsub("+", "%20"))
request = Net::HTTP::Delete.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("EXECUTOR_CLIENT_SECRET")}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
raise "Request failed: #{response.code}" unless response.is_a?(Net::HTTPSuccess)
puts response.body

1
2
3
4curl --fail-with-body \
  --request DELETE \
  --header "Authorization: Bearer $EXECUTOR_CLIENT_SECRET" \
  "$WORKER_URL/executors/$SESSION_ID"

Delete the Agents API session separately. Session deletion does not emit a webhook, so perform both operations for immediate cleanup. Retrieve files you need before releasing the Container.

Advanced: Application-managed provisioning

For direct control of sandbox provisioning, use the Cloudflare Sandbox SDK with the application-managed lifecycle and executor connection instructions. Use one provisioning controller per session.

References

Read Use Cloudflare Containers with OpenAI Agents API for configuration, lifecycle behavior, snapshots, and image customization.
Read Cloudflare Sandbox documentation.
Read Cloudflare Sandbox TypeScript SDK reference.

Suggested

Get started

Core concepts

SDKs and CLI

Resources

Legacy APIs

Choose a model

Text and code

Prompting

Reasoning

Images and video

Realtime and audio

Specialized models

Agents API

Agents SDK

ChatKit

Search and retrieval

Connect tools and data

Build tool workflows

Computer and code

Media

GPT-Live

Realtime API

Build with voice

Connections

Audio processing

Go live

Performance and quality

Cost and throughput

Safety and governance

Infrastructure and access

Operations

Core concepts

Plan

Build

Test and publish

Conversion specs

Guides

Resources

Get started

Guides

File Upload

API

Measurement

Advertiser API

API Reference

Get started

Foundations

Explore

Available on

Releases

Workflows

Capabilities

Reference

Customization

Config file

Agent configuration

Extend ChatGPT and Codex

Linux

Windows

Development workflows

Extend and automate

Environments

Build with Codex

Third-party integrations

Reference

Permissions

Codex Security

Cyber safety

Getting started

ChatGPT Work

Identity and authentication

Workspace access, policy, and models

Plugin and connector controls

Usage, governance, and compliance

Deployment and model providers

Community

Blog

Community

Blog