@tanstack/ai-sandbox-cloudflare 0.1.0

package/src/handle.ts

@@ -0,0 +1,292 @@
+/**
+ * SandboxHandle backed by a Cloudflare Sandbox (Containers + Durable Objects),
+ * via `@cloudflare/sandbox`. Runs at the edge inside a Worker.
+ *
+ * fs is implemented over `exec` with base64 piping (binary-safe), matching the
+ * Docker provider. The container disk is EPHEMERAL (wiped to the image on
+ * restart) and snapshots are not yet GA, so `capabilities.snapshots` and
+ * `durableFilesystem` are false — `withSandbox` re-bootstraps under the same
+ * identity across cold starts.
+ *
+ * LIMITATION: Cloudflare background processes do not expose a writable host→
+ * process stdin, so `spawn().stdin.write` throws. This is advertised via
+ * `capabilities.writableStdin: false`; harness adapters that feed a prompt over
+ * stdin (e.g. the Claude Code adapter) detect this and instead deliver the
+ * prompt via a file + shell stdin-redirection (`claude -p … < file`), which the
+ * in-container shell handles with no host-side stdin write. `exec` (one-shot)
+ * and streamed stdout from `spawn` both work fully.
+ *
+ * NOTE: not runtime-verified in this repo (requires a Workers runtime); it
+ * compiles against the real `@cloudflare/sandbox` types and follows the proven
+ * provider contract.
+ */
+import { createExecBackedGit } from '@tanstack/ai-sandbox'
+import type { Sandbox } from '@cloudflare/sandbox'
+import type {
+  ExecResult,
+  ProcessOptions,
+  SandboxCapabilities,
+  SandboxChannel,
+  SandboxHandle,
+  SpawnHandle,
+} from '@tanstack/ai-sandbox'
+
+export const CLOUDFLARE_CAPS: SandboxCapabilities = {
+  fs: true,
+  exec: true,
+  env: true,
+  ports: true,
+  backgroundProcesses: true,
+  // No writable host→process stdin; stdin-fed harnesses use file-redirection.
+  writableStdin: false,
+  snapshots: false,
+  networkPolicy: false,
+  durableFilesystem: false,
+  fork: false,
+}
+
+/** POSIX single-quote escape for embedding paths in `sh -c`. */
+function q(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`
+}
+
+/** A push-driven async string queue used to adapt CF's onOutput callback. */
+class OutputQueue {
+  private readonly buffer: Array<string> = []
+  private readonly waiters: Array<(r: IteratorResult<string>) => void> = []
+  private ended = false
+
+  push(value: string): void {
+    const waiter = this.waiters.shift()
+    if (waiter) waiter({ value, done: false })
+    else this.buffer.push(value)
+  }
+
+  end(): void {
+    this.ended = true
+    let waiter = this.waiters.shift()
+    while (waiter) {
+      waiter({ value: undefined, done: true })
+      waiter = this.waiters.shift()
+    }
+  }
+
+  async *[Symbol.asyncIterator](): AsyncIterator<string> {
+    while (!this.ended || this.buffer.length > 0) {
+      if (this.buffer.length > 0) {
+        yield this.buffer.shift() as string
+        continue
+      }
+      const next = await new Promise<IteratorResult<string>>((resolve) =>
+        this.waiters.push(resolve),
+      )
+      if (next.done) return
+      yield next.value
+    }
+  }
+}
+
+export class CloudflareHandle implements SandboxHandle {
+  readonly id: string
+  readonly provider = 'cloudflare'
+  readonly workspaceRoot: string
+  readonly capabilities = CLOUDFLARE_CAPS
+  readonly fs: SandboxHandle['fs']
+  readonly git: SandboxHandle['git']
+  readonly process: SandboxHandle['process']
+  readonly ports: SandboxHandle['ports']
+  readonly env: SandboxHandle['env']
+
+  private readonly sandbox: Sandbox
+  private readonly workdir: string
+  private readonly previewHostname: string | undefined
+
+  constructor(
+    id: string,
+    sandbox: Sandbox,
+    workdir: string,
+    previewHostname?: string,
+  ) {
+    this.id = id
+    this.sandbox = sandbox
+    this.workdir = workdir
+    this.workspaceRoot = workdir
+    this.previewHostname = previewHostname
+
+    this.process = {
+      exec: (command, opts) => this.exec(command, opts),
+      spawn: (command, opts) => this.spawnProcess(command, opts),
+    }
+
+    this.fs = {
+      read: async (p) => {
+        const r = await this.exec(`base64 ${q(this.abs(p))}`)
+        if (r.exitCode !== 0) throw new Error(`read failed: ${r.stderr.trim()}`)
+        return Buffer.from(r.stdout, 'base64').toString('utf8')
+      },
+      readBytes: async (p) => {
+        const r = await this.exec(`base64 ${q(this.abs(p))}`)
+        if (r.exitCode !== 0) throw new Error(`read failed: ${r.stderr.trim()}`)
+        return new Uint8Array(Buffer.from(r.stdout, 'base64'))
+      },
+      write: async (p, data) => {
+        const abs = this.abs(p)
+        const b64 = Buffer.from(
+          typeof data === 'string' ? Buffer.from(data, 'utf8') : data,
+        ).toString('base64')
+        const dir = abs.replace(/\/[^/]*$/, '') || '/'
+        const r = await this.exec(
+          `mkdir -p ${q(dir)} && printf %s ${q(b64)} | base64 -d > ${q(abs)}`,
+        )
+        if (r.exitCode !== 0)
+          throw new Error(`write failed: ${r.stderr.trim()}`)
+      },
+      list: async (p) => {
+        const r = await this.exec(`ls -1Ap ${q(this.abs(p))}`)
+        if (r.exitCode !== 0) throw new Error(`list failed: ${r.stderr.trim()}`)
+        return r.stdout
+          .split('\n')
+          .filter((line) => line.trim() !== '')
+          .map((entry) => {
+            const isDir = entry.endsWith('/')
+            const name = isDir ? entry.slice(0, -1) : entry
+            return {
+              name,
+              path: `${p.replace(/\/$/, '')}/${name}`,
+              type: isDir ? ('dir' as const) : ('file' as const),
+            }
+          })
+      },
+      mkdir: async (p) => {
+        await this.exec(`mkdir -p ${q(this.abs(p))}`)
+      },
+      remove: async (p) => {
+        await this.exec(`rm -rf ${q(this.abs(p))}`)
+      },
+      rename: async (from, to) => {
+        await this.exec(`mv ${q(this.abs(from))} ${q(this.abs(to))}`)
+      },
+      exists: async (p) => {
+        const r = await this.exec(`test -e ${q(this.abs(p))}`)
+        return r.exitCode === 0
+      },
+    }
+
+    this.git = createExecBackedGit(this.process, this.workdir)
+
+    this.ports = {
+      connect: (port) => this.connectPort(port),
+    }
+
+    this.env = {
+      set: (vars) => this.sandbox.setEnvVars(vars),
+    }
+  }
+
+  private abs(p: string): string {
+    if (this.workdir === '/workspace') return p
+    if (p === '/workspace') return this.workdir
+    if (p.startsWith('/workspace/')) {
+      return `${this.workdir}/${p.slice('/workspace/'.length)}`
+    }
+    return p
+  }
+
+  private async exec(
+    command: string,
+    opts?: ProcessOptions,
+  ): Promise<ExecResult> {
+    const result = await this.sandbox.exec(command, {
+      ...(opts?.cwd ? { cwd: this.abs(opts.cwd) } : { cwd: this.workdir }),
+      ...(opts?.env ? { env: opts.env } : {}),
+    })
+    return {
+      stdout: result.stdout,
+      stderr: result.stderr,
+      exitCode: result.exitCode,
+    }
+  }
+
+  private spawnProcess(
+    command: string,
+    opts?: ProcessOptions,
+  ): Promise<SpawnHandle> {
+    const stdout = new OutputQueue()
+    const stderr = new OutputQueue()
+
+    // Stream over `exec({ stream: true, onOutput })` — the SAME proven command
+    // path as one-shot `exec`. The background-process API (`startProcess` +
+    // `streamProcessLogs`) does NOT deliver its `onOutput`/`onExit` callbacks
+    // here (verified under `wrangler dev`: the process runs and exits cleanly,
+    // yet no log events ever arrive), so a stdout-NDJSON harness spawned that
+    // way hangs forever. exec's streaming path emits each chunk via `onOutput`
+    // and resolves with the exit code on completion. The prompt still reaches
+    // the CLI via in-shell stdin redirection (`… < file`), which this session
+    // shell honors — `writableStdin` stays false.
+    //
+    // The caller's AbortSignal is intentionally NOT forwarded: `exec` is a
+    // Durable Object RPC and Workers RPC cannot serialize an AbortSignal
+    // ("AbortSignal serialization is not enabled"), so passing one throws
+    // before the command runs. Mid-run cancellation is therefore unavailable
+    // on this provider; a stuck run is bounded by the coordinator's watchdog
+    // and the Durable Object lifecycle instead. `kill()` is a best-effort no-op.
+    const settled = this.sandbox.exec(command, {
+      ...(opts?.cwd ? { cwd: this.abs(opts.cwd) } : { cwd: this.workdir }),
+      ...(opts?.env ? { env: opts.env } : {}),
+      stream: true,
+      onOutput: (stream, data) => {
+        if (stream === 'stdout') stdout.push(data)
+        else stderr.push(data)
+      },
+    })
+    // End the output queues once the command settles either way (so the stdout
+    // reader terminates), but let a failure REJECT `wait()` rather than masking
+    // it as a clean exit — the harness adapter turns that into a RUN_ERROR
+    // instead of a silent zero-output run.
+    const exitPromise = settled.then(
+      (result) => {
+        stdout.end()
+        stderr.end()
+        return result.exitCode
+      },
+      (error: unknown) => {
+        stdout.end()
+        stderr.end()
+        throw error
+      },
+    )
+
+    return Promise.resolve({
+      pid: -1,
+      stdout,
+      stderr,
+      stdin: {
+        write: () =>
+          Promise.reject(
+            new Error(
+              'cloudflare: background processes do not expose stdin. Use exec(), or a stdin-capable provider (local-process / docker) for stdin-fed harnesses.',
+            ),
+          ),
+        end: () => Promise.resolve(),
+      },
+      wait: () => exitPromise,
+      kill: () => Promise.resolve(),
+    })
+  }
+
+  private async connectPort(port: number): Promise<SandboxChannel> {
+    if (this.previewHostname === undefined) {
+      throw new Error(
+        'cloudflare: ports.connect requires a previewHostname. Pass previewHostname (your Worker request hostname) to cloudflareSandbox(...).',
+      )
+    }
+    const { url } = await this.sandbox.exposePort(port, {
+      hostname: this.previewHostname,
+    })
+    return { url }
+  }
+
+  async destroy(): Promise<void> {
+    await this.sandbox.destroy()
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export { cloudflareSandbox } from './provider'
+export type { CloudflareSandboxConfig } from './provider'
+export { CloudflareHandle, CLOUDFLARE_CAPS } from './handle'
+// Re-export the Sandbox class so users can wire the Durable Object binding.
+export { Sandbox } from '@cloudflare/sandbox'

package/src/preview-tool.ts

@@ -0,0 +1,110 @@
+/**
+ * The browser-preview capability, as reusable building blocks rather than
+ * per-app glue: a `chat()` server tool that mints a preview URL for a dev server
+ * running inside the sandbox, plus the system-prompt guidance an agent needs to
+ * produce a preview that works.
+ *
+ * Previews go over a **Cloudflare quick tunnel** (`sandbox.tunnels.get(port)` →
+ * `https://<name>.trycloudflare.com`), served by `cloudflared` INSIDE the sandbox.
+ * We deliberately do NOT use `exposePort` + `proxyToSandbox` here: that routes the
+ * preview through the Worker's own origin, which in local dev is the example's Vite
+ * dev server — and Vite's middleware then serves the preview's module/asset
+ * requests (`/@vite/client`, `/src/*`, `/@fs/*`) from the HOST instead of the
+ * container, breaking the page. A tunnel bypasses the Vite port entirely, needs no
+ * custom domain on a deploy, and forwards WebSockets (so the app's HMR works).
+ *
+ * Both exports belong to THIS package because the transport is its concern, not any
+ * particular app's. Wire them explicitly into your agent:
+ *
+ * ```ts
+ * import {
+ *   exposePreviewTool,
+ *   PREVIEW_GUIDANCE,
+ * } from '@tanstack/ai-sandbox-cloudflare/agent'
+ *
+ * createCloudflareSandboxAgent({
+ *   adapter: () => claudeCodeText('sonnet'),
+ *   tools: (input, env) => [exposePreviewTool(input, env)],
+ *   systemPrompts: [PREVIEW_GUIDANCE],
+ * })
+ * ```
+ *
+ * Workers-only (imports `@cloudflare/sandbox`) — exported from the `/agent` entry.
+ */
+import { toolDefinition } from '@tanstack/ai'
+import { z } from 'zod'
+import { getSandbox } from '@cloudflare/sandbox'
+import type { Sandbox } from '@cloudflare/sandbox'
+import type { StartRunInput } from './coordinator'
+
+/**
+ * The minimum env an {@link exposePreviewTool} needs: the Sandbox namespace it
+ * addresses the run's container in. `SandboxAgentEnv` satisfies this structurally,
+ * so the factory's `tools` resolver passes its env straight in.
+ */
+export interface PreviewToolEnv {
+  Sandbox: DurableObjectNamespace<Sandbox>
+}
+
+/**
+ * System-prompt guidance for any agent that exposes a dev server as a browser
+ * preview. App-agnostic: the only requirement a quick tunnel imposes is that the
+ * dev server accept the tunnel hostname (Vite/webpack reject unknown hosts by
+ * default), so the rule is "bind wide + allow all hosts", not "disable HMR" — the
+ * tunnel forwards WebSockets, so HMR works.
+ */
+export const PREVIEW_GUIDANCE: string = [
+  'PREVIEW SERVERS: to show the user a running web app, start its dev server bound',
+  'to 0.0.0.0 on a port OTHER than 3000 (3000 is reserved by the sandbox control',
+  'plane), then call the `exposePreview` tool with that port. It returns a public',
+  'Cloudflare quick-tunnel URL (https://<name>.trycloudflare.com) served straight',
+  'from the sandbox — no custom domain needed, and HMR / live-reload WebSockets',
+  'work through the tunnel (you do NOT need to disable HMR). The ONE requirement:',
+  'the dev server must ACCEPT the tunnel hostname, which servers reject by default,',
+  'so allow all hosts in its config before starting:',
+  '• Vite — `server: { host: true, allowedHosts: true }` in vite.config.',
+  "• webpack-dev-server — `allowedHosts: 'all'` (and `host: '0.0.0.0'`).",
+  '• Other dev servers — bind 0.0.0.0 and allow all hosts equivalently.',
+  'Once it is listening, call `exposePreview` with that port, then share the URL.',
+].join('\n')
+
+/**
+ * Build the `exposePreview` server tool for one run. Starting a tunnel is a
+ * HOST-side call on the Sandbox DO stub, so an in-sandbox agent cannot make it from
+ * bash — it calls this bridged tool instead. We address the run's container by
+ * `threadId` and open (or reuse) a quick tunnel to the given port.
+ *
+ * Closes over the run's `input` + `env`, so build it inside the `tools` resolver
+ * (`tools: (input, env) => [exposePreviewTool(input, env)]`).
+ */
+export function exposePreviewTool(input: StartRunInput, env: PreviewToolEnv) {
+  return toolDefinition({
+    name: 'exposePreview',
+    description:
+      'Expose a port a dev server is listening on inside the sandbox and return a public preview URL (a Cloudflare quick tunnel) to show the user. Call this AFTER the server is up. The dev server must allow all hosts (e.g. Vite `server.allowedHosts: true`) so it accepts the tunnel hostname.',
+    inputSchema: z.object({
+      port: z
+        .number()
+        .int()
+        .min(1024)
+        .max(65535)
+        .describe('The port the dev server is listening on, e.g. 5173.'),
+    }),
+  }).server(async ({ port }) => {
+    // `sandbox.tunnels` only exists on the RPC transport (on HTTP/WebSocket it's a
+    // stub that throws "requires the RPC transport"), so we must obtain the stub
+    // with `transport: 'rpc'`. IMPORTANT: this must MATCH how the sandbox was
+    // created — pass `transport: 'rpc'` on EVERY `getSandbox()` for this id (in your
+    // sandbox provider too), or the differing transport disconnects the run's active
+    // client. See the SDK `SandboxOptions.transport` note.
+    const sandbox = getSandbox(env.Sandbox, input.threadId, {
+      transport: 'rpc',
+    })
+    // A Cloudflare quick tunnel (`*.trycloudflare.com`) run by `cloudflared` INSIDE
+    // the sandbox: it bypasses the local Vite dev server's port entirely (so Vite
+    // can't hijack the preview's asset requests) and needs no custom domain on a
+    // deploy. `get(port)` is idempotent per port. See the Sandbox SDK `tunnels` API.
+    const tunnel = await sandbox.tunnels.get(port)
+    return { url: tunnel.url }
+  })
+}

package/src/protocol.ts

@@ -0,0 +1,171 @@
+/**
+ * The wire contract for the ONE request that crosses the DO → container boundary
+ * to start a run: `POST /run` on the in-container runner.
+ *
+ * Defined ONCE here so both sides import the same shape AND the same narrowing
+ * guard, with NO runtime-specific imports (no `cloudflare:*`, no `node:*`):
+ *  - the `ContainerSandboxCoordinator` (Workers side) builds a
+ *    {@link ContainerRunRequest} and POSTs it (re-exported from `/agent`);
+ *  - the in-container `runInContainerHarness` (Node side) validates the body
+ *    with {@link parseContainerRunRequest} before running `chat()` (imported
+ *    from `/runner`).
+ *
+ * It carries the run identity + conversation + serialized host-tool descriptors
+ * + the tool-exec callback, plus the `harness`/`model`/`workspace` the runner
+ * needs to build the right adapter and sandbox.
+ *
+ * NOTE: the workspace's secret VALUES do NOT cross this boundary — `createSecrets`
+ * stores them under a non-enumerable symbol, so JSON-serializing the workspace
+ * carries only the secret NAMES. The runner reconstructs runtime secrets from
+ * the container env (the DO injects them via `sandbox.setEnvVars`).
+ */
+import type { ModelMessage } from '@tanstack/ai'
+import type { ToolDescriptor, WorkspaceDefinition } from '@tanstack/ai-sandbox'
+
+/**
+ * The in-sandbox harnesses the runner can spawn. Single source of truth: the
+ * {@link HarnessId} type is DERIVED from this list, and {@link isHarnessId}
+ * validates against it — so the runtime guard and the compile-time type can
+ * never drift.
+ */
+const HARNESS_IDS = ['claude-code', 'codex', 'opencode'] as const
+
+/**
+ * Identifier for the in-sandbox harness the runner spawns. The runner maps this
+ * to the matching `*Text` adapter (via the caller's `resolveAdapter`); the DO
+ * never imports the adapter packages.
+ */
+export type HarnessId = (typeof HARNESS_IDS)[number]
+
+/**
+ * The body of `POST /run`: the run identity + conversation + serialized
+ * host-tool descriptors + the tool-exec callback, plus the harness/model/
+ * workspace the runner needs to build the right adapter.
+ */
+export interface ContainerRunRequest {
+  runId: string
+  threadId: string
+  messages: Array<ModelMessage>
+  harness: HarnessId
+  model: string
+  workspace: WorkspaceDefinition
+  /** Host-tool descriptors serialized by `toolDescriptors()` on the DO. */
+  toolDescriptors: Array<ToolDescriptor>
+  /** DO endpoint the in-container `httpRemoteToolExecutor` POSTs tool calls to. */
+  toolExecUrl: string
+  /** Per-run bearer token gating that tool-exec endpoint. */
+  toolExecToken: string
+}
+
+function isHarnessId(value: unknown): value is HarnessId {
+  return (
+    typeof value === 'string' &&
+    (HARNESS_IDS as ReadonlyArray<string>).includes(value)
+  )
+}
+
+function isToolDescriptor(value: unknown): value is ToolDescriptor {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    'name' in value &&
+    typeof value.name === 'string'
+  )
+}
+
+function isWorkspaceDefinition(value: unknown): value is WorkspaceDefinition {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    'source' in value &&
+    value.source !== null &&
+    typeof value.source === 'object'
+  )
+}
+
+/**
+ * Assert enough of a message to fail fast on garbage (a non-empty `role` and a
+ * `content` field). The chat engine validates the full shape downstream; this
+ * narrows the array element to {@link ModelMessage} without a cast.
+ */
+function isModelMessage(value: unknown): value is ModelMessage {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    'role' in value &&
+    typeof value.role === 'string' &&
+    'content' in value
+  )
+}
+
+/** Narrow `unknown` to an indexable record (a predicate, not a cast). */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object'
+}
+
+function requireNonEmptyString(
+  value: Record<string, unknown>,
+  key: string,
+): string {
+  const found = value[key]
+  if (typeof found !== 'string' || found === '') {
+    throw new Error(`run request: ${key} must be a non-empty string`)
+  }
+  return found
+}
+
+/**
+ * Narrow an unknown `POST /run` body into a {@link ContainerRunRequest} (project
+ * rule: no `as`). The message and descriptor shapes are validated downstream by
+ * the chat engine and the tool bridge; here we only assert enough to fail fast
+ * with a clear error on a malformed request.
+ */
+export function parseContainerRunRequest(value: unknown): ContainerRunRequest {
+  if (!isRecord(value)) {
+    throw new Error('run request must be a JSON object')
+  }
+  const runId = requireNonEmptyString(value, 'runId')
+  const threadId = requireNonEmptyString(value, 'threadId')
+  const model = requireNonEmptyString(value, 'model')
+  const toolExecUrl = requireNonEmptyString(value, 'toolExecUrl')
+  const toolExecToken = requireNonEmptyString(value, 'toolExecToken')
+
+  const messages = value['messages']
+  if (
+    !Array.isArray(messages) ||
+    messages.length === 0 ||
+    !messages.every(isModelMessage)
+  ) {
+    throw new Error('run request: messages must be a non-empty ModelMessage[]')
+  }
+
+  const harness = value['harness']
+  if (!isHarnessId(harness)) {
+    throw new Error('run request: harness must be a known harness id')
+  }
+
+  const workspace = value['workspace']
+  if (!isWorkspaceDefinition(workspace)) {
+    throw new Error('run request: workspace must be a WorkspaceDefinition')
+  }
+
+  const toolDescriptors = value['toolDescriptors']
+  if (
+    !Array.isArray(toolDescriptors) ||
+    !toolDescriptors.every(isToolDescriptor)
+  ) {
+    throw new Error('run request: toolDescriptors must be a ToolDescriptor[]')
+  }
+
+  return {
+    runId,
+    threadId,
+    messages,
+    harness,
+    model,
+    workspace,
+    toolDescriptors,
+    toolExecUrl,
+    toolExecToken,
+  }
+}

package/src/provider.ts

@@ -0,0 +1,111 @@
+import { getSandbox } from '@cloudflare/sandbox'
+import { CLOUDFLARE_CAPS, CloudflareHandle } from './handle'
+import type { Sandbox, SandboxTransport } from '@cloudflare/sandbox'
+import type {
+  SandboxCapabilities,
+  SandboxCreateInput,
+  SandboxDestroyInput,
+  SandboxHandle,
+  SandboxProvider,
+  SandboxResumeInput,
+} from '@tanstack/ai-sandbox'
+
+const DEFAULT_WORKDIR = '/workspace'
+
+export interface CloudflareSandboxConfig {
+  /**
+   * The Sandbox Durable Object namespace binding (e.g. `env.Sandbox`).
+   * Available inside a Worker `fetch` handler.
+   */
+  binding: DurableObjectNamespace<Sandbox>
+  /** Working directory inside the container. Defaults to `/workspace`. */
+  workdir?: string
+  /**
+   * Your Worker's request hostname, required by `ports.connect` to expose a
+   * preview URL (Cloudflare routes exposed ports by hostname).
+   */
+  previewHostname?: string
+  /**
+   * Container-control transport. Defaults to `'rpc'` (the SDK's primary path)
+   * because `sandbox.tunnels` — used by `exposePreviewTool` to mint quick-tunnel
+   * preview URLs — ONLY exists on the RPC transport; on `'http'`/`'websocket'` it
+   * throws "requires the RPC transport". The transport must be the same for every
+   * `getSandbox()` of a given id, so this provider applies it to create/resume/
+   * destroy alike. Override to `'http'` only if you don't use preview tunnels.
+   */
+  transport?: SandboxTransport
+}
+
+class CloudflareProvider implements SandboxProvider {
+  readonly name = 'cloudflare'
+
+  constructor(private readonly config: CloudflareSandboxConfig) {}
+
+  capabilities(): SandboxCapabilities {
+    return CLOUDFLARE_CAPS
+  }
+
+  private get workdir(): string {
+    return this.config.workdir ?? DEFAULT_WORKDIR
+  }
+
+  // `transport: 'rpc'` by default so `sandbox.tunnels` (preview URLs) works; must be
+  // identical across every `getSandbox()` for an id, so all three paths share this.
+  private get sandboxOptions(): { transport: SandboxTransport } {
+    return { transport: this.config.transport ?? 'rpc' }
+  }
+
+  async create(input: SandboxCreateInput): Promise<SandboxHandle> {
+    const id = crypto.randomUUID()
+    const sandbox = getSandbox(this.config.binding, id, this.sandboxOptions)
+    if (input.env && Object.keys(input.env).length > 0) {
+      await sandbox.setEnvVars(input.env)
+    }
+    await sandbox.mkdir(this.workdir, { recursive: true })
+    return new CloudflareHandle(
+      id,
+      sandbox,
+      this.workdir,
+      this.config.previewHostname,
+    )
+  }
+
+  resume(input: SandboxResumeInput): Promise<SandboxHandle | null> {
+    // The Durable Object is durable, so the sandbox is always addressable by
+    // id. (The container disk may have been wiped on cold start — withSandbox
+    // re-bootstraps under the same identity when durableFilesystem is false.)
+    const sandbox = getSandbox(
+      this.config.binding,
+      input.id,
+      this.sandboxOptions,
+    )
+    return Promise.resolve(
+      new CloudflareHandle(
+        input.id,
+        sandbox,
+        this.workdir,
+        this.config.previewHostname,
+      ),
+    )
+  }
+
+  async destroy(input: SandboxDestroyInput): Promise<void> {
+    const sandbox = getSandbox(
+      this.config.binding,
+      input.id,
+      this.sandboxOptions,
+    )
+    await sandbox.destroy()
+  }
+}
+
+/**
+ * Cloudflare sandbox provider — runs harness adapters inside Cloudflare
+ * Containers at the edge. Construct it inside a Worker with the Sandbox Durable
+ * Object namespace binding. See the stdin/snapshot limitations in `handle.ts`.
+ */
+export function cloudflareSandbox(
+  config: CloudflareSandboxConfig,
+): SandboxProvider {
+  return new CloudflareProvider(config)
+}