Container runtime

目录

import { Render } from "~/components";

<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/", title: "Sandboxes" }} />

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:

# 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:

Example:

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()):

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

Background processes (startProcess()):

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

Network capabilities

Outbound connections work:

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

Inbound connections require port exposure:

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

:::note[Local development] When using wrangler dev, you must add EXPOSE directives to your Dockerfile for each port. See Local development with ports. :::

Localhost works within sandbox:

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

Security

Between sandboxes (isolated):

Within sandbox (shared):

To run untrusted code, use separate sandboxes per user:

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

Limitations

Cannot:

版本号 #2
由 壳壳虫 创建于 2026-11-01 04:10:40 UTC
由 壳壳虫 更新于 2026-11-01 04:10:42 UTC