Skip to content

Background

Coming From Vercel, E2B or Modal

Simple Chainguard Sandbox SDK borrows its shape from three sandbox SDKs:

  • E2B (closest match): Sandbox.create(), the sandbox.commands and sandbox.files namespaces, commands.run returning a result or (with background) 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 exec style, 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.

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

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.)
# E2B
from e2b import Sandbox
with Sandbox.create() as sbx:
r = sbx.commands.run("echo hi")
sbx.files.write("/home/user/a.txt", "x")
# Simple Chainguard Sandbox SDK
from chainguard_sandbox import Sandbox
with Sandbox.create() as sbx:
r = sbx.commands.run("echo hi")
sbx.files.write("/work/a.txt", "x") # or just "a.txt"