Build secure, isolated code execution environments
The Sandbox SDK enables you to run untrusted code securely in isolated environments. Built on Containers, Sandbox SDK provides a simple API for executing commands, managing files, running background processes, and exposing services — all from your Workers applications.
Sandboxes are ideal for building AI agents that need to execute code, interactive development environments, data analysis platforms, CI/CD systems, and any application that needs secure code execution at the edge. Each sandbox runs in its own isolated container with a full Linux environment, providing strong security boundaries while maintaining performance.
With Sandbox, you can execute Python scripts, run Node.js applications, analyze data, compile code, and perform complex computations — all with a simple TypeScript API and no infrastructure to manage.
import { getSandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const sandbox = getSandbox(env.Sandbox, 'user-123');
// Execute a command and get the result
const result = await sandbox.exec('python --version');
return Response.json({
output: result.stdout,
exitCode: result.exitCode,
success: result.success
});
}
};import { getSandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const sandbox = getSandbox(env.Sandbox, 'user-123');
// Create a Python execution context
const ctx = await sandbox.createCodeContext({ language: 'python' });
// Execute Python code with automatic result capture
const result = await sandbox.runCode(`
import pandas as pd
data = {'product': ['A', 'B', 'C'], 'sales': [100, 200, 150]}
df = pd.DataFrame(data)
df['sales'].sum() # Last expression is automatically returned
`, { context: ctx });
return Response.json({
result: result.results?.[0]?.text,
logs: result.logs
});
}
};import { getSandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const sandbox = getSandbox(env.Sandbox, 'user-123');
// Create a project structure
await sandbox.mkdir('/workspace/project/src', { recursive: true });
// Write files
await sandbox.writeFile(
'/workspace/project/package.json',
JSON.stringify({ name: 'my-app', version: '1.0.0' })
);
// Read a file back
const content = await sandbox.readFile('/workspace/project/package.json');
return Response.json({ content });
}
};import { getSandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const sandbox = getSandbox(env.Sandbox, 'user-123');
// Watch for file changes in real-time
const watcher = await sandbox.watch('/workspace/src', {
include: ['*.js', '*.ts'],
onEvent: (event) => {
console.log(`${event.type}: ${event.path}`);
if (event.type === 'modify') {
// Trigger rebuild or hot reload
console.log('Code changed, recompiling...');
}
},
onError: (error) => {
console.error('Watch error:', error);
}
});
// Stop watching when done
setTimeout(() => watcher.stop(), 60000);
return Response.json({ message: 'File watcher started' });
}
};import { getSandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const url = new URL(request.url);
// Terminal WebSocket connection
if (url.pathname === '/ws/terminal') {
const sandbox = getSandbox(env.Sandbox, 'user-123');
return sandbox.terminal(request, { cols: 80, rows: 24 });
}
return Response.json({ message: 'Terminal endpoint' });
}
};Connect browser terminals directly to sandbox shells via WebSocket. Learn more: Browser terminals.
import { getSandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';
export default {
async fetch(request: Request, env: Env): Promise<Response> {
// Connect to WebSocket services in sandbox
if (request.headers.get('Upgrade')?.toLowerCase() === 'websocket') {
const sandbox = getSandbox(env.Sandbox, 'user-123');
return await sandbox.wsConnect(request, 8080);
}
return Response.json({ message: 'WebSocket endpoint' });
}
};Connect to WebSocket servers running in sandboxes. Learn more: WebSocket Connections.
Get started
API Reference
Run shell commands, Python scripts, Node.js applications, and more with streaming output support and automatic timeout handling.
Read, write, and manipulate files in the sandbox filesystem. Run background processes, monitor output, and manage long-running operations.
Expose HTTP services running in your sandbox with automatically generated preview URLs, perfect for interactive development environments and application hosting.
Execute Python and JavaScript code with rich outputs including charts, tables, and images. Maintain persistent state between executions for AI-generated code and interactive workflows.
Create browser-based terminal interfaces that connect directly to sandbox shells via WebSocket. Build collaborative terminals, interactive development environments, and real-time shell access with automatic reconnection.
Mount S3-compatible object storage (R2, S3, GCS, and more) as local filesystems. Access buckets using standard file operations with data that persists across sandbox lifecycles. Production deployment required.
Monitor files and directories for changes using native filesystem events. Perfect for building hot reloading development servers, build automation systems, and configuration monitoring tools.
Keep credentials in your Worker while allowing sandboxes to access external APIs. A Worker proxy validates short-lived JWT tokens from the sandbox and injects real credentials at request time.
Build powerful applications with Sandbox:
Execute code generated by Large Language Models safely and reliably. Native integration with Workers AI models like GPT-OSS enables function calling with sandbox execution. Perfect for AI agents, code assistants, and autonomous systems that need to run untrusted code.
Create interactive data analysis environments with pandas, NumPy, and Matplotlib. Generate charts, tables, and visualizations with automatic rich output formatting.
Build cloud IDEs, coding playgrounds, and collaborative development tools with full Linux environments and preview URLs.
Run tests, compile code, and execute build pipelines in isolated environments with parallel execution and streaming logs.
Serverless container runtime that powers Sandbox, enabling you to run any containerized workload on the edge.
Run machine learning models and LLMs on the network. Combine with Sandbox for secure AI code execution workflows.
Stateful coordination layer that enables Sandbox to maintain persistent environments with strong consistency.
Tutorials
Explore complete examples including AI code execution, data analysis, and interactive environments.
How-to Guides
Learn how to solve specific problems and implement features with the Sandbox SDK.
API reference
Explore the complete API documentation for the Sandbox SDK.
Concepts
Learn about the key concepts and architecture of the Sandbox SDK.
Configuration
Learn about the configuration options for the Sandbox SDK.
GitHub Repository
View the SDK source code, report issues, and contribute to the project.
Pricing
Understand Sandbox pricing based on the underlying Containers platform.
Limits
Learn about resource limits, quotas, and best practices for working within them.
Discord Community
Connect with the community on Discord. Ask questions, share what you're building, and get help from other developers.