Cloudflare Sandbox SDK


Build secure, isolated code execution environments on Cloudflare.

The Sandbox SDK lets you run untrusted code safely in isolated containers. Execute commands, manage files, run background processes, and expose services — all from your Workers applications.

Perfect for AI code execution, interactive development environments, data analysis platforms, CI/CD systems, and any application that needs secure code execution at the edge.

Getting Started

$3

1. Install Node.js (version 16.17.0 or later)
2. Ensure Docker is running locally (see setup guide)
3. For deploying to production, sign up for a Cloudflare account

$3

Create a new Sandbox SDK project using the minimal template:

``bash
npm create cloudflare@latest -- my-sandbox --template=cloudflare/sandbox-sdk/examples/minimal
cd my-sandbox
`

$3

Start the development server:

`bash
npm run dev
`

> Note: First run builds the Docker container (2-3 minutes). Subsequent runs are much faster.

Test the endpoints:

`bash


Execute Python code

curl http://localhost:8787/run

File operations

curl http://localhost:8787/file
`

$3

Deploy your Worker and container:

`bash
npx wrangler deploy
`

> Wait for provisioning: After first deployment, wait 2-3 minutes before making requests.

📖 View the complete getting started guide for detailed instructions and explanations.

Quick API Example

`typescript
import { getSandbox, proxyToSandbox, type Sandbox } from '@cloudflare/sandbox';

export { Sandbox } from '@cloudflare/sandbox';

type Env = {
Sandbox: DurableObjectNamespace;
};

export default {
async fetch(request: Request, env: Env): Promise {
// Required for preview URLs
const proxyResponse = await proxyToSandbox(request, env);
if (proxyResponse) return proxyResponse;

const url = new URL(request.url);
const sandbox = getSandbox(env.Sandbox, 'my-sandbox');

// Execute Python code
if (url.pathname === '/run') {
const result = await sandbox.exec('python3 -c "print(2 + 2)"');
return Response.json({ output: result.stdout, success: result.success });
}

// Work with files
if (url.pathname === '/file') {
await sandbox.writeFile('/workspace/hello.txt', 'Hello, Sandbox!');
const file = await sandbox.readFile('/workspace/hello.txt');
return Response.json({ content: file.content });
}

return new Response('Try /run or /file');
}
};
`

Documentation

📖 Full Documentation

- Get Started Guide - Step-by-step tutorial
- API Reference - Complete API docs
- Guides - Execute commands, manage files, expose services
- Examples - AI agents, data analysis, CI/CD pipelines

Key Features

- Secure Isolation - Each sandbox runs in its own container
- Edge-Native - Runs on Cloudflare's global network
- Code Interpreter - Execute Python and JavaScript with rich outputs
- File System Access - Read, write, and manage files
- Command Execution - Run any command with streaming support
- Preview URLs - Expose services with public URLs
- Git Integration - Clone repositories directly

Contributing

We welcome contributions from the community! See CONTRIBUTING.md for guidelines on:

- Setting up your development environment
- Creating pull requests
- Code style and testing requirements

Development

This repository contains the SDK source code. Quick start:

`bash


Clone the repo

git clone https://github.com/cloudflare/sandbox-sdk
cd sandbox-sdk

Install dependencies

npm install

Run tests

npm test

Build the project

npm run build

Type checking and linting

npm run check
`

Examples

See the examples directory for complete working examples:

- Minimal - Start here: exec commands, read/write files
- Code Interpreter - Give gpt-oss on Workers AI a Python REPL
- Claude Code - Run Claude Code headless on any repo
- OpenAI Agents - Shell and Editor` tools for OpenAI Agents SDK
- OpenCode - OpenCode web UI or SDK in a sandbox
- TypeScript Validator - Build with npm in sandbox, execute in isolates

Status

Beta - The SDK is in active development. APIs may change before v1.0.

License

Apache License 2.0

Links

- Documentation
- GitHub Issues
- Developer Discord
- Cloudflare Developers