HTTP API reference

Last updated Sep 30, 2026 Note

This page documents Sandbox SDK 0.x for existing applications. For new applications, refer to Sandboxes. To move an existing application to @cloudflare/sandbox 1.0, refer to Migrate from Sandbox SDK 0.x.

This page documents every route exposed by the sandbox bridge on the stable template.

Authentication

All routes under /v1/sandbox/* and /v1/openapi.* require a Bearer token:

Authorization: Bearer <SANDBOX_API_KEY>

When SANDBOX_API_KEY is not configured, authentication is skipped for local development convenience. Always set the secret before deploying to production.

OpenAPI schema

The bridge serves its own API documentation:

Both routes accept authentication via Bearer header or ?token= query parameter.

When running locally with npm run dev, open http://localhost:8787/v1/openapi in your browser to explore every endpoint interactively.

Sandbox lifecycle

Command execution

The /exec endpoint accepts a JSON body:

{
  "argv": ["sh", "-lc", "echo hello"],
  "timeout_ms": 10000,
  "cwd": "/workspace"
}

Argv escaping

Each element of the argv array is escaped using ANSI-C $'...' quoting before being joined into a shell command. Tokens that contain only safe characters (A-Za-z0-9@%+=:,./-) are passed through unchanged. All other tokens are wrapped in $'...' with backslashes, single quotes, newlines, carriage returns, and tabs escaped. This prevents shell injection while preserving arguments that contain spaces, quotes, or special characters.

SSE response format

The response is a text/event-stream with the following event types:

File operations

The file path is encoded in the URL after /file/. All paths must resolve within /workspace. Path traversal attempts (for example, ../../etc/passwd) are rejected.

Workspace persistence

The /persist endpoint accepts an optional excludes query parameter — a comma-separated list of relative paths to exclude from the archive.

The /hydrate endpoint accepts a raw tar payload up to 32 MiB.

Bucket mounts

The /mount endpoint accepts a JSON body. Two flows are supported:

R2 binding mounts

Omit endpoint and pass the Worker R2 binding name in bucket:

{
  "bucket": "MY_BUCKET",
  "mountPath": "/mnt/data",
  "options": {
    "readOnly": false,
    "prefix": "/subdir"
  }
}

When options.endpoint is omitted, bucket means the Worker R2 binding name.

For an explicit S3-compatible endpoint mount, include endpoint and optionally credentials:

{
  "bucket": "my-r2-bucket",
  "mountPath": "/mnt/data",
  "options": {
    "endpoint": "https://ACCOUNT_ID.r2.cloudflarestorage.com",
    "readOnly": false,
    "prefix": "/subdir",
    "credentials": {
      "accessKeyId": "...",
      "secretAccessKey": "..."
    }
  }
}

When endpoint is provided, bucket means the remote bucket name. Credentials are optional in this mode only — the bridge auto-detects from Worker secrets (R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY or AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY) when omitted.

Sessions

Sessions isolate working directory, environment variables, and command execution state within a sandbox. Pass the Session-Id header on /exec, /file/*, and /pty requests to scope them to a session.

When no Session-Id header is provided, requests use the sandbox's implicit execution mode. By default this is the default session, but SDKs configured with enableDefaultSession: false run those implicit operations sessionless instead.

Terminal (PTY)

Query parameters:

The WebSocket carries binary frames for terminal I/O and JSON text frames for control messages:

Warm pool

The warm pool pre-starts sandbox containers so new sessions boot instantly. Configure it with environment variables in wrangler.jsonc:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "vars": {
    "WARM_POOL_TARGET": "3",
    "WARM_POOL_REFRESH_INTERVAL": "10000"
  }
}

[vars]
WARM_POOL_TARGET = "3"           # Number of idle containers to keep warm (0 = disabled)
WARM_POOL_REFRESH_INTERVAL = "10000"  # Health-check interval in milliseconds

A cron trigger (* * * * *) primes the pool automatically after deployment. Set WARM_POOL_TARGET to "0" (the default) to disable the pool and avoid unexpected costs.

Health check

Related resources

• Bridge overview — What the bridge is, deployment, and usage examples.
• Sandbox API reference — Complete Sandbox SDK method reference.
• Bridge source on GitHub ↗︎ — Worker, Dockerfile, and OpenAPI schema.

Was this helpful?

YesNo

On this page

Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/sandbox/sdk/bridge/http-api/#page","headline":"HTTP API reference","description":"Complete HTTP API reference for the Sandbox SDK 0.x bridge Worker.","url":"https://developers.cloudflare.com/sandbox/sdk/bridge/http-api/","inLanguage":"en","image":"https://developers.cloudflare.com/sandbox/sdk/bridge/http-api/og.png?v=06ca7849a95e2ba9","dateModified":"2026-09-30","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Learn how the Sandbox SDK 0.x works, including architecture, lifecycle, security, and sessions. title: Concepts image: https://developers.cloudflare.com/sandbox/sdk/concepts/og.png?v=84623be765317a51

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/sandbox/llms.txt
Use this file to discover all available pages before exploring further.