Skip to content
Cloudflare Docs

Container runtime

Each sandbox runs in an isolated Linux container with Python, Node.js, and common development tools pre-installed. For a complete list of pre-installed software and how to customize the container image, see Dockerfile reference.

Runtime software installation

Install additional software at runtime using standard package managers:

Terminal window
# Python packages
pip install scikit-learn tensorflow


# Node.js packages
npm install express


# System packages (requires apt-get update first)
apt-get update && apt-get install -y redis-server

Filesystem

The container provides a standard Linux filesystem. You can read and write anywhere you have permissions.

Standard directories:

  • /workspace - Default working directory for user code
  • /tmp - Temporary files
  • /home - User home directory
  • /usr/bin, /usr/local/bin - Executable binaries

Example:

TypeScript
await sandbox.writeFile('/workspace/app.py', 'print("Hello")');
await sandbox.writeFile('/tmp/cache.json', '{}');
await sandbox.exec('ls -la /workspace');

Process management

Processes run as you'd expect in a regular Linux environment.

Foreground processes (exec()):

TypeScript
const result = await sandbox.exec('npm test');
// Waits for completion, returns output

Background processes (startProcess()):

TypeScript
const process = await sandbox.startProcess('node server.js');
// Returns immediately, process runs in background

Memory management

The container runtime includes optimizations for long-running sandboxes with many processes:

  • Active processes are kept in memory for fast access
  • Completed processes are persisted to disk (/tmp/sandbox-internal/processes/) and freed from memory to prevent unbounded growth
  • Stream listeners are automatically cleaned up when streaming operations complete or are cancelled

These optimizations ensure stable memory usage even for sandboxes that execute hundreds or thousands of processes over their lifetime. Process history remains queryable after completion via the standard process APIs.

Network capabilities

Outbound connections work:

Terminal window
curl https://api.example.com/data
pip install requests
npm install express

Inbound connections require port exposure:

TypeScript
const { hostname } = new URL(request.url);
await sandbox.startProcess('python -m http.server 8000');
const exposed = await sandbox.exposePort(8000, { hostname });
console.log(exposed.exposedAt); // Public URL

Localhost works within sandbox:

Terminal window
redis-server &      # Start server
redis-cli ping      # Connect locally

Security

Between sandboxes (isolated):

  • Each sandbox is a separate container
  • Filesystem, memory and network are all isolated

Within sandbox (shared):

  • All processes see the same files
  • Processes can communicate with each other
  • Environment variables are session-scoped

To run untrusted code, use separate sandboxes per user:

TypeScript
const sandbox = getSandbox(env.Sandbox, `user-${userId}`);

Limitations

Cannot:

  • Load kernel modules or access host hardware
  • Run nested containers (no Docker-in-Docker)