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

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
await sandbox.startProcess('python -m http.server 8000');
const exposed = await sandbox.exposePort(8000);
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)