Code Sandbox

Run a JavaScript snippet in an isolated environment using the Cloudflare Sandbox SDK (@cloudflare/sandbox) backed by Containers and a Durable Object.

API ReferenceCopy Anchor Link

POST /execCopy Anchor Link

Execute code and return stdout, stderr, and exit code.

language string (required)

Currently only javascript is supported.

code string (required)

Snippet to run. Max length 5,000 characters.

Example RequestCopy Anchor Link

curl -X POST "https://your-worker.workers.dev/exec" \
  -H "Content-Type: application/json" \
  -d '{"language":"javascript","code":"console.log(2 + 2)"}'

Success ResponseCopy Anchor Link

{
  "stdout": "4\n",
  "stderr": "",
  "exitCode": 0
}

Error CodesCopy Anchor Link

• 400 - Invalid body, language, or code (INVALID_BODY, INVALID_LANGUAGE, INVALID_CODE)
• 502 - Sandbox execution failure (EXEC_ERROR)

Use CasesCopy Anchor Link

• Learn Sandbox SDK getSandbox + exec patterns
• Safely evaluate untrusted JavaScript snippets at the edge
• Prototype coding tutors or REPL APIs
• Compare Sandbox containers vs Dynamic Workers isolation

LimitationsCopy Anchor Link

• Only javascript is supported in this demo
• Code max length 5,000 characters
• Docker required for local wrangler dev / deploy
• Container max_instances is 1 (lite instance type)

Use in your projectCopy Anchor Link

import { SANDBOX_ID, SNIPPET_PATH } from "../constants/defaults";import type { Env } from "../types/env";import type { ExecResult } from "../types/exec";export type SandboxClient = {  writeFile(path: string, content: string): Promise<unknown>;  exec(command: string): Promise<{    stdout: string;    stderr: string;    exitCode: number;  }>;};export type GetSandboxFn = (namespace: Env["Sandbox"], id: string) => SandboxClient;let getSandboxImpl: GetSandboxFn | null = null;/** Test hook to inject a mock sandbox without Docker / cloudflare: imports. */export function setGetSandboxForTests(fn: GetSandboxFn | null): void {  getSandboxImpl = fn;}async function resolveSandbox(env: Env): Promise<SandboxClient> {  if (getSandboxImpl) {    return getSandboxImpl(env.Sandbox, SANDBOX_ID);  }  const { getSandbox } = await import("@cloudflare/sandbox");  // Env uses untyped DO namespace for Node/vitest; cast for Sandbox SDK.  return getSandbox(    env.Sandbox as unknown as Parameters<typeof getSandbox>[0],    SANDBOX_ID  ) as unknown as SandboxClient;}export async function execJavascript(env: Env, code: string): Promise<ExecResult> {  const sandbox = await resolveSandbox(env);  await sandbox.writeFile(SNIPPET_PATH, code);  const result = await sandbox.exec(`node ${SNIPPET_PATH}`);  return {    stdout: result.stdout ?? "",    stderr: result.stderr ?? "",    exitCode: result.exitCode ?? 1,  };}

DeploymentCopy Anchor Link

curl -X POST "https://your-worker.workers.dev/exec" \
  -H "Content-Type: application/json" \
  -d '{"language":"javascript","code":"console.log(2 + 2)"}'

Local DevelopmentCopy Anchor Link

Docker must be running for container image builds.

cd apps/experiments/code-sandbox
npm install
npm run dev

curl -X POST "http://localhost:8787/exec" \
  -H "Content-Type: application/json" \
  -d '{"language":"javascript","code":"console.log(2 + 2)"}'

Unit tests mock the sandbox client so Docker is not required for npm run test.

ConfigurationCopy Anchor Link

wrangler.json declares:

• Container Sandbox from ./Dockerfile (instance_type: lite)
• Durable Object binding Sandbox → class Sandbox
• Compatibility flag nodejs_compat

Cloudflare Features UsedCopy Anchor Link

• Workers - Edge compute runtime
• Sandbox SDK - Isolated code execution
• Containers - Official sandbox image
• Durable Objects - Sandbox class binding