chore: simplify cloudflare compatibility

Author: NathanFlurry

docs/deploy/cloudflare.mdx

@@ -31,18 +31,23 @@ RUN sandbox-agent install-agent claude && sandbox-agent install-agent codex
 EXPOSE 8000
 ```
 
-## TypeScript proxy example
+## TypeScript example
 
 ```typescript
 import { getSandbox, type Sandbox } from "@cloudflare/sandbox";
+import { Hono } from "hono";
+import { SandboxAgent } from "sandbox-agent";
+
 export { Sandbox } from "@cloudflare/sandbox";
 
-type Env = {
+type Bindings = {
   Sandbox: DurableObjectNamespace<Sandbox>;
+  ASSETS: Fetcher;
   ANTHROPIC_API_KEY?: string;
   OPENAI_API_KEY?: string;
 };
 
+const app = new Hono<{ Bindings: Bindings }>();
 const PORT = 8000;
 
 async function isServerRunning(sandbox: Sandbox): Promise<boolean> {
@@ -54,64 +59,50 @@ async function isServerRunning(sandbox: Sandbox): Promise<boolean> {
   }
 }
 
-async function ensureRunning(sandbox: Sandbox, env: Env): Promise<void> {
-  if (await isServerRunning(sandbox)) return;
-
-  const envVars: Record<string, string> = {};
-  if (env.ANTHROPIC_API_KEY) envVars.ANTHROPIC_API_KEY = env.ANTHROPIC_API_KEY;
-  if (env.OPENAI_API_KEY) envVars.OPENAI_API_KEY = env.OPENAI_API_KEY;
-  await sandbox.setEnvVars(envVars);
-
-  await sandbox.startProcess(`sandbox-agent server --no-token --host 0.0.0.0 --port ${PORT}`);
-
-  for (let i = 0; i < 30; i++) {
-    if (await isServerRunning(sandbox)) return;
-    await new Promise((r) => setTimeout(r, 200));
+async function getReadySandbox(name: string, env: Bindings): Promise<Sandbox> {
+  const sandbox = getSandbox(env.Sandbox, name);
+  if (!(await isServerRunning(sandbox))) {
+    const envVars: Record<string, string> = {};
+    if (env.ANTHROPIC_API_KEY) envVars.ANTHROPIC_API_KEY = env.ANTHROPIC_API_KEY;
+    if (env.OPENAI_API_KEY) envVars.OPENAI_API_KEY = env.OPENAI_API_KEY;
+    await sandbox.setEnvVars(envVars);
+    await sandbox.startProcess(`sandbox-agent server --no-token --host 0.0.0.0 --port ${PORT}`);
   }
-
-  throw new Error("sandbox-agent failed to start");
+  return sandbox;
 }
 
-export default {
-  async fetch(request: Request, env: Env): Promise<Response> {
-    const url = new URL(request.url);
-    const match = url.pathname.match(/^\/sandbox\/([^/]+)(\/.*)?$/);
+app.post("/sandbox/:name/prompt", async (c) => {
+  const sandbox = await getReadySandbox(c.req.param("name"), c.env);
 
-    if (!match) {
-      return new Response("Not found", { status: 404 });
-    }
+  const sdk = await SandboxAgent.connect({
+    fetch: (input, init) => sandbox.containerFetch(input as Request | string | URL, init, PORT),
+  });
 
-    const [, name, path = "/"] = match;
-    const sandbox = getSandbox(env.Sandbox, name);
-    await ensureRunning(sandbox, env);
+  const session = await sdk.createSession({ agent: "codex" });
+  const response = await session.prompt([{ type: "text", text: "Summarize this repository" }]);
+  await sdk.destroySession(session.id);
+  await sdk.dispose();
 
-    return sandbox.containerFetch(
-      new Request(`http://localhost${path}${url.search}`, request),
-      PORT,
-    );
-  },
-};
-```
-
-## Connect from a client
-
-```typescript
-import { SandboxAgent } from "sandbox-agent";
-
-const sdk = await SandboxAgent.connect({
-  baseUrl: "http://localhost:8787/sandbox/my-sandbox",
+  return c.json(response);
 });
 
-const session = await sdk.createSession({ agent: "claude" });
+app.all("/sandbox/:name/proxy/*", async (c) => {
+  const sandbox = await getReadySandbox(c.req.param("name"), c.env);
+  const wildcard = c.req.param("*");
+  const path = wildcard ? `/${wildcard}` : "/";
+  const query = new URL(c.req.raw.url).search;
 
-const off = session.onEvent((event) => {
-  console.log(event.sender, event.payload);
+  return sandbox.containerFetch(new Request(`http://localhost${path}${query}`, c.req.raw), PORT);
 });
 
-await session.prompt([{ type: "text", text: "Summarize this repository" }]);
-off();
+app.all("*", (c) => c.env.ASSETS.fetch(c.req.raw));
+
+export default app;
 ```
 
+Create the SDK client inside the Worker using custom `fetch` backed by `sandbox.containerFetch(...)`.
+This keeps all Sandbox Agent calls inside the Cloudflare sandbox routing path and does not require a `baseUrl`.
+
 ## Local development
 
 ```bash
@@ -121,7 +112,7 @@ npm run dev
 Test health:
 
 ```bash
-curl http://localhost:8787/sandbox/demo/v1/health
+curl http://localhost:8787/sandbox/demo/proxy/v1/health
 ```
 
 ## Production deployment

docs/sdk-overview.mdx

@@ -39,6 +39,14 @@ const sdk = await SandboxAgent.connect({
 });
 ```
 
+With a custom fetch handler (for example, proxying requests inside Workers):
+
+```ts
+const sdk = await SandboxAgent.connect({
+  fetch: (input, init) => customFetch(input, init),
+});
+```
+
 With persistence:
 
 ```ts
@@ -158,9 +166,10 @@ console.log(url);
 
 Parameters:
 
-- `baseUrl` (required): Sandbox Agent server URL
+- `baseUrl` (required unless `fetch` is provided): Sandbox Agent server URL
 - `token` (optional): Bearer token for authenticated servers
 - `headers` (optional): Additional request headers
+- `fetch` (optional): Custom fetch implementation used by SDK HTTP and ACP calls
 
 ## Types
 

examples/cloudflare/README.md

@@ -36,6 +36,16 @@ Test the endpoint:
 curl http://localhost:8787
 ```
 
+Test prompt routing through the SDK with a custom sandbox fetch handler:
+
+```bash
+curl -X POST "http://localhost:8787/sandbox/demo/prompt" \
+  -H "Content-Type: application/json" \
+  -d '{"agent":"codex","prompt":"Reply with one short sentence."}'
+```
+
+The response includes `events`, an array of all recorded session events for that prompt.
+
 ## Deploy
 
 ```bash

examples/cloudflare/frontend/App.tsx

@@ -25,7 +25,7 @@ export function App() {
 
     try {
       // Connect via proxy endpoint (need full URL for SDK)
-      const baseUrl = `${window.location.origin}/sandbox/${encodeURIComponent(sandboxName)}`;
+      const baseUrl = `${window.location.origin}/sandbox/${encodeURIComponent(sandboxName)}/proxy`;
       log(`Connecting to sandbox: ${sandboxName}`);
 
       const client = await SandboxAgent.connect({ baseUrl });

examples/cloudflare/package.json

@@ -10,6 +10,7 @@
   },
   "dependencies": {
     "@cloudflare/sandbox": "latest",
+    "hono": "^4.12.2",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "sandbox-agent": "workspace:*"

examples/cloudflare/src/index.ts

@@ -1,16 +1,20 @@
 import { getSandbox, type Sandbox } from "@cloudflare/sandbox";
+import { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { runPromptTest, type PromptTestRequest } from "./prompt-test";
 
 export { Sandbox } from "@cloudflare/sandbox";
 
-type Env = {
-  Bindings: {
-    Sandbox: DurableObjectNamespace<Sandbox>;
-    ASSETS: Fetcher;
-    ANTHROPIC_API_KEY?: string;
-    OPENAI_API_KEY?: string;
-  };
+type Bindings = {
+  Sandbox: DurableObjectNamespace<Sandbox>;
+  ASSETS: Fetcher;
+  ANTHROPIC_API_KEY?: string;
+  OPENAI_API_KEY?: string;
+  CODEX_API_KEY?: string;
 };
 
+type AppEnv = { Bindings: Bindings };
+
 const PORT = 8000;
 
 /** Check if sandbox-agent is already running by probing its health endpoint */
@@ -23,54 +27,60 @@ async function isServerRunning(sandbox: Sandbox): Promise<boolean> {
   }
 }
 
-/** Ensure sandbox-agent is running in the container */
-async function ensureRunning(sandbox: Sandbox, env: Env["Bindings"]): Promise<void> {
-  if (await isServerRunning(sandbox)) return;
-
-  // Set environment variables for agents
+async function getReadySandbox(name: string, env: Bindings): Promise<Sandbox> {
+  const sandbox = getSandbox(env.Sandbox, name);
   const envVars: Record<string, string> = {};
   if (env.ANTHROPIC_API_KEY) envVars.ANTHROPIC_API_KEY = env.ANTHROPIC_API_KEY;
   if (env.OPENAI_API_KEY) envVars.OPENAI_API_KEY = env.OPENAI_API_KEY;
+  if (env.CODEX_API_KEY) envVars.CODEX_API_KEY = env.CODEX_API_KEY;
+  if (!envVars.CODEX_API_KEY && envVars.OPENAI_API_KEY) envVars.CODEX_API_KEY = envVars.OPENAI_API_KEY;
   await sandbox.setEnvVars(envVars);
 
-  // Start sandbox-agent server as background process
-  await sandbox.startProcess(`sandbox-agent server --no-token --host 0.0.0.0 --port ${PORT}`);
+  if (!(await isServerRunning(sandbox))) {
+    await sandbox.startProcess(`sandbox-agent server --no-token --host 0.0.0.0 --port ${PORT}`);
 
-  // Poll health endpoint until server is ready (max ~6 seconds)
-  for (let i = 0; i < 30; i++) {
-    if (await isServerRunning(sandbox)) return;
-    await new Promise((r) => setTimeout(r, 200));
+    for (let i = 0; i < 30; i++) {
+      if (await isServerRunning(sandbox)) break;
+      await new Promise((r) => setTimeout(r, 200));
+    }
   }
+  return sandbox;
 }
 
-export default {
-  async fetch(request: Request, env: Env["Bindings"]): Promise<Response> {
-    const url = new URL(request.url);
-
-    // Proxy requests to sandbox-agent: /sandbox/:name/v1/...
-    const match = url.pathname.match(/^\/sandbox\/([^/]+)(\/.*)?$/);
-    if (match) {
-      if (!env.ANTHROPIC_API_KEY && !env.OPENAI_API_KEY) {
-        return Response.json(
-          { error: "ANTHROPIC_API_KEY or OPENAI_API_KEY must be set" },
-          { status: 500 }
-        );
-      }
-
-      const name = match[1];
-      const path = match[2] || "/";
-      const sandbox = getSandbox(env.Sandbox, name);
-
-      await ensureRunning(sandbox, env);
-
-      // Proxy request to container
-      return sandbox.containerFetch(
-        new Request(`http://localhost${path}${url.search}`, request),
-        PORT
-      );
-    }
+async function proxyToSandbox(sandbox: Sandbox, request: Request, path: string): Promise<Response> {
+  const query = new URL(request.url).search;
+  return sandbox.containerFetch(new Request(`http://localhost${path}${query}`, request), PORT);
+}
+
+const app = new Hono<AppEnv>();
+
+app.onError((error) => {
+  return new Response(String(error), { status: 500 });
+});
+
+app.post("/sandbox/:name/prompt", async (c) => {
+  if (!(c.req.header("content-type") ?? "").includes("application/json")) {
+    throw new HTTPException(400, { message: "Content-Type must be application/json" });
+  }
+
+  let payload: PromptTestRequest;
+  try {
+    payload = await c.req.json<PromptTestRequest>();
+  } catch {
+    throw new HTTPException(400, { message: "Invalid JSON body" });
+  }
+
+  const sandbox = await getReadySandbox(c.req.param("name"), c.env);
+  return c.json(await runPromptTest(sandbox, payload, PORT));
+});
+
+app.all("/sandbox/:name/proxy/*", async (c) => {
+  const sandbox = await getReadySandbox(c.req.param("name"), c.env);
+  const wildcard = c.req.param("*");
+  const path = wildcard ? `/${wildcard}` : "/";
+  return proxyToSandbox(sandbox, c.req.raw, path);
+});
+
+app.all("*", (c) => c.env.ASSETS.fetch(c.req.raw));
 
-    // Serve frontend assets
-    return env.ASSETS.fetch(request);
-  },
-} satisfies ExportedHandler<Env["Bindings"]>;
+export default app;

examples/cloudflare/src/prompt-test.ts

@@ -0,0 +1,66 @@
+import type { Sandbox } from "@cloudflare/sandbox";
+import { SandboxAgent } from "sandbox-agent";
+
+export type PromptTestRequest = {
+	agent?: string;
+	prompt?: string;
+};
+
+export type PromptTestResponse = {
+	sessionId: string;
+	agent: string;
+	prompt: string;
+	events: unknown[];
+};
+
+export async function runPromptTest(
+	sandbox: Sandbox,
+	request: PromptTestRequest,
+	port: number,
+): Promise<PromptTestResponse> {
+	const client = await SandboxAgent.connect({
+		fetch: (req, init) =>
+			sandbox.containerFetch(req, init, port),
+	});
+
+	let sessionId: string | null = null;
+	try {
+		const session = await client.createSession({
+			agent: request.agent ?? "codex",
+		});
+		sessionId = session.id;
+
+		const promptText =
+			request.prompt?.trim() || "Reply with a short confirmation.";
+		await session.prompt([{ type: "text", text: promptText }]);
+
+		const events: unknown[] = [];
+		let cursor: string | undefined;
+		while (true) {
+			const page = await client.getEvents({
+				sessionId: session.id,
+				cursor,
+				limit: 200,
+			});
+			events.push(...page.items);
+			if (!page.nextCursor) break;
+			cursor = page.nextCursor;
+		}
+
+		return {
+			sessionId: session.id,
+			agent: session.agent,
+			prompt: promptText,
+			events,
+		};
+	} finally {
+		if (sessionId) {
+			try {
+				await client.destroySession(sessionId);
+			} catch {
+				// Ignore cleanup failures; session teardown is best-effort.
+			}
+		}
+		await client.dispose();
+	}
+}