Background
Coming From Vercel, E2B or Modal
Simple Chainguard Sandbox SDK borrows its shape from three sandbox SDKs:
- E2B (closest match):
Sandbox.create(), thesandbox.commandsandsandbox.filesnamespaces,commands.runreturning a result or (withbackground) a handle, and errors that carry the result. - Vercel Sandbox: argv commands without a shell, batched file writes,
await using, and file download. - Modal Sandboxes: argv
execstyle, directory copies, and pause/snapshot semantics.
The tables below map each SDK’s main calls to this API. The other SDKs’ names come from their published
packages as of November 2026: Vercel @vercel/sandbox 3.9, E2B e2b 2.63 and Modal modal 1.6.
Creating and Managing Sandboxes
Section titled “Creating and Managing Sandboxes”| Vercel Sandbox (TS) | E2B (TS / Py) | Modal (Py) | Simple Chainguard Sandbox SDK (TS / Py / Go / Rust) | |
|---|---|---|---|---|
| Create | Sandbox.create({image, resources, ports, timeout, env}) |
Sandbox.create({template, timeoutMs, envs, metadata}) |
modal.Sandbox.create(app=, image=, timeout=, env=) |
Sandbox.create({packages, envs, egress}) / Sandbox.create(packages=…) / sandbox.Create(ctx, &CreateOptions{…}) / Sandbox::create(CreateOptions {…}) |
| Toolchain | image (container) |
template (built from a Dockerfile/builder) |
image=modal.Image… |
packages: a Chainguard package list (no container images) |
| Reconnect | Sandbox.get({name}) |
Sandbox.connect(id) |
Sandbox.from_id(id) |
Sandbox.connect(id) / sandbox.Connect(ctx, id, nil) / Sandbox::connect(id, …) |
| List | Sandbox.list() |
Sandbox.list() |
Sandbox.list(app_id=) |
Sandbox.list() / sandbox.List(ctx, nil) / chainguard_sandbox::list(…) |
| Delete | stop() / delete() |
kill() / Sandbox.kill(id) |
terminate() |
kill() / Sandbox.kill(id) / Kill(ctx) / chainguard_sandbox::kill(id, …) |
| Scoped cleanup | await using (stops) |
Python with (kills); none in JS |
try/finally |
Python with, TS await using (both kill), Go defer sb.Kill(ctx), Rust Sandbox::with(…, async |sbx| …) |
| Pause / resume | persistent by default, auto-resume | pause() / connect() |
snapshot_filesystem(), memory snapshots (alpha) |
pause(); any later call resumes it, with processes intact |
| Lifetime limit | timeout (5 min default, extendTimeout) |
timeoutMs (5 min, setTimeout) |
timeout (5 min), idle_timeout |
No timeout: parks after ~10 min idle; keep_alive(seconds) holds it awake |
| Info | getters on the sandbox | getInfo(), isRunning() |
poll(), returncode |
get_info() / getInfo() / GetInfo(ctx), is_running() |
Commands
Section titled “Commands”| Vercel Sandbox | E2B | Modal | Simple Chainguard Sandbox SDK | |
|---|---|---|---|---|
| Run and wait | runCommand(cmd, args) |
commands.run("shell string") |
sb.exec(*argv) then .wait() |
commands.run("shell string") or commands.run([argv…]); Go Run / RunArgs; Rust run / run_args |
| Shell? | no (argv) | yes (bash -l -c) |
no (argv) | string → bash -lc; list/array → argv |
| Non-zero exit | returned (exitCode) |
throws CommandExitError |
returned (wait()) |
throws CommandExitError (it carries the result) |
| Output | await result.stdout() |
result.stdout |
p.stdout.read() |
result.stdout |
| Streaming | stdout: Writable, logs() |
onStdout, onStderr |
iterate p.stdout |
on_stdout / onStdout / OnStdout |
| cwd / env | cwd, env |
cwd, envs |
workdir=, env= |
cwd, envs |
| Timeout | timeoutMs |
timeoutMs (60 s default) |
timeout= |
timeout (s) / timeoutMs / Timeout / timeout: Some(Duration), 60 s default |
| stdin | stdin: Readable / writeStdin |
stdin: true + sendStdin |
p.stdin.write() |
stdin bytes up front (≤ 16 MiB); no interactive stdin |
| Background | detached: true → Command |
background: true → CommandHandle |
every exec is a process | background: true / background=True → CommandHandle; Go Start; Rust start |
| Handle | wait(), kill(), logs() |
wait(), kill(), pid, sendStdin |
wait(), poll(), returncode |
wait(), poll(), kill(), pid, stdout, stderr |
| Reattach | getCommand(id) |
commands.connect(pid) |
— | commands.connect(pid), commands.list(), commands.kill(pid) |
| Concurrency | concurrent commands | concurrent commands | concurrent execs | one foreground command at a time; use background commands |
| Vercel Sandbox | E2B | Modal | Simple Chainguard Sandbox SDK | |
|---|---|---|---|---|
| Write one | writeFiles([{path, content}]) |
files.write(path, data) |
filesystem.write_bytes(data, path) |
files.write(path, data) |
| Write many | writeFiles([...]) |
files.write([...]) / write_files |
— | files.write([...]) / write_files / WriteFiles |
| Read | readFileToBuffer({path}) (null if missing) |
files.read(path, {format}) |
filesystem.read_text/read_bytes |
files.read(path, format); missing → FileNotFoundError |
| List / stat | fs.readdir / fs.stat |
files.list, getInfo, exists |
list_files, stat |
files.list, get_info, exists |
| mkdir / rm / mv | mkDir, fs.rm, fs.rename |
makeDir, remove, rename |
make_directory, remove |
make_dir, remove, rename |
| Local ↔ sandbox | downloadFile |
upload/download URLs | copy_from_local, copy_to_local |
upload, download, upload_dir, download_dir |
| Relative paths | against /vercel |
against /home/user |
must be absolute | against /work |
| User | ubuntu (sudo) |
user |
root | root |
Networking
Section titled “Networking”| Vercel Sandbox | E2B | Modal | Simple Chainguard Sandbox SDK | |
|---|---|---|---|---|
| Public URL for a port | ports + domain(port) |
getHost(port) |
encrypted_ports + tunnels() |
not available |
| Outbound policy | networkPolicy (allow/deny lists, header injection) |
allowInternetAccess, network.allowOut/denyOut |
block_network, outbound_*_allowlist |
egress hostname allowlist + egress_policy (“deny”/“destroy”); a mandatory deny floor |
| Credential brokering | header-injecting firewall rules | header-injecting rules | experimental outbound policy | Workspaces brokers git, Claude, GCP and Chainguard credentials (not exposed by this package) |
Not Available Here
Section titled “Not Available Here”These exist in at least one of the other SDKs and have no equivalent in Simple Chainguard Sandbox SDK, usually because the Workspaces service doesn’t offer them:
- Many concurrent sandboxes: one per user and three per organization (the Workspaces beta limits).
- Exposed ports and public URLs.
- Custom container images and templates (only package lists).
- A hard sandbox timeout (
timeout,setTimeout,extendTimeout). - Interactive stdin to a running command, and PTYs. The Workspaces API has interactive terminals, but this SDK doesn’t expose them.
- Tags/metadata, filesystem snapshots you can fork, volumes and mounts.
- GPUs, resource sizing (fixed at 4 vCPU / 16 GB), and region choice.
- Async Python (
AsyncSandbox): the Python package is synchronous. (The Rust crate is async, with a blocking module.)
Porting Examples
Section titled “Porting Examples”# E2Bfrom e2b import Sandboxwith Sandbox.create() as sbx: r = sbx.commands.run("echo hi") sbx.files.write("/home/user/a.txt", "x")
# Simple Chainguard Sandbox SDKfrom chainguard_sandbox import Sandboxwith Sandbox.create() as sbx: r = sbx.commands.run("echo hi") sbx.files.write("/work/a.txt", "x") # or just "a.txt"// Vercel Sandboxconst sandbox = await Sandbox.create({ timeout: 60_000 });await sandbox.writeFiles([{ path: "hello.js", content: Buffer.from("console.log('hi')") }]);const r = await sandbox.runCommand("node", ["hello.js"]);if (r.exitCode !== 0) throw new Error(await r.stderr());console.log(await r.stdout());await sandbox.stop();
// Simple Chainguard Sandbox SDK: argv form, errors throw, stdout is a propertyconst sbx = await Sandbox.create();await sbx.files.write([{ path: "hello.js", data: "console.log('hi')" }]);const r = await sbx.commands.run(["node", "hello.js"]);console.log(r.stdout);await sbx.kill();# Modalsb = modal.Sandbox.create(app=app, image=modal.Image.debian_slim().pip_install("numpy"))p = sb.exec("python", "-c", "import numpy; print(numpy.__version__)")print(p.stdout.read())sb.terminate()
# Simple Chainguard Sandbox SDK: packages instead of an imagesbx = Sandbox.create(packages=["python-3.13", "py3.13-numpy"])print(sbx.commands.run(["python3", "-c", "import numpy; print(numpy.__version__)"]).stdout)sbx.kill()Python libraries come either as Chainguard packages (py3.13-<name>, if packaged) or from
pip install inside the sandbox.
