HTTP API reference

This page documents every route exposed by the sandbox bridge.

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.

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.

The /exec endpoint accepts a JSON body:

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

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.

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

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.

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.

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

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 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.

Query parameters:

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

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.

• 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.