npm version

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.

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

Create a new Sandbox SDK project using the minimal template:

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

Start the development server:

npm run dev

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

Test the endpoints:

# Execute Python code
curl http://localhost:8787/run
# File operations
curl http://localhost:8787/file

Deploy your Worker and container:

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.

import { getSandbox, proxyToSandbox, type Sandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';
type Env = {
 Sandbox: DurableObjectNamespace<Sandbox>;
};
export default {
 async fetch(request: Request, env: Env): Promise<Response> {
 // 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');
 }
};

📖 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

• 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

This repository contains the SDK source code. To contribute:

# 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

See the examples directory for complete working examples:

• Minimal - Basic sandbox setup
• Code Interpreter - Use sandbox as an interpreter tool with gpt-oss
• Complete - Huge example integrated with every sandbox feature

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

MIT License

• Documentation
• GitHub Issues
• Developer Discord
• Cloudflare Developers