Guides
Environments and Network
A sandbox has no container image. Its toolchain comes from an environment document: a list of
Chainguard packages plus a network policy. The service resolves the document when the sandbox is created.
This is where Workspaces differs most from image-based sandboxes, and it plays the role of Vercel’s
image, E2B’s templates and Modal’s Image.
Packages
Section titled “Packages”Sandbox.create(packages=["bash", "coreutils", "python-3.12", "py3.12-pip", "nodejs-22", "go"])- Package names: these are Chainguard / Wolfi names, versioned where it
matters:
python-3.13,python-3.12,py3.12-pip,nodejs-22,go,go-1.24,bun,jq,curl,git, … All of these were checked against the resolver. - Default:
bash,coreutils,curl,git,jq,python-3.13,nodejs-22(DEFAULT_PACKAGES). Passing your own list replaces the default. - Always installed: busybox, git, gh, chainctl, curl, bash, bash-completion, ripgrep, gnutar.
- Unknown names fail
createwith the resolver’s message (the environment does not resolve: …), before any sandbox exists. - Installing at run time: listing packages up front is the supported way.
apk addat run time needsapk-toolsin the list, and wasn’t tested with this package. Either way, run-time installs don’t carry over to new sandboxes. - Language-level packages: install with the language’s own tool inside the sandbox (
pip install,npm install,cargo install). The network must allow it; see below.
Network
Section titled “Network”Outbound traffic is open by default (egress = ["*"]). Narrow it with an allowlist of hostnames:
Sandbox.create(egress=["pypi.org", "files.pythonhosted.org"])await Sandbox.create({ egress: ["pypi.org", "files.pythonhosted.org"] });sandbox.Create(ctx, &sandbox.CreateOptions{Egress: []string{"pypi.org", "files.pythonhosted.org"}})Sandbox::create(CreateOptions { egress: Some(vec!["pypi.org".into(), "files.pythonhosted.org".into()]), ..Default::default()}).await?;- Verified live: with
egress: [example.com],https://example.comanswered 200 andhttps://www.wikipedia.orgwas refused. egress=[]allows no hosts.egress_policy/egressPolicy/EgressPolicydecides what happens to a connection outside the allowlist:"deny"(the default) refuses the connection and the sandbox keeps running;"destroy"tears the sandbox down.- Always blocked, whatever the allowlist: cloud metadata endpoints, loopback and private address ranges.
- Interception: ports 80 and 443 go through transparent HTTPS interception with a per-sandbox CA. That’s how hostnames are filtered, and why the sandbox trusts a CA you didn’t install.
- No inbound traffic: there’s no way to expose a port or get a public URL. See Limits.
A Custom Environment Document
Section titled “A Custom Environment Document”For anything the options don’t cover, pass a whole document. Packages and egress are then ignored. The generated one looks like this:
# Generated by chainguard-sandbox-sdk.version: 1environment: packages: - "bash" - "python-3.13"checks: develop: network: egress: - "*" policy: "deny"It’s the same format as a repository’s .chainguard/ci.yaml: an environment plus one check named
develop, whose network block applies to the sandbox. environment_document() (Python),
environmentDocument() (TypeScript), sandbox.Document() (Go) and chainguard_sandbox::document() (Rust)
return what create would send, so you can start from it.
Starting From a GitHub Repository
Section titled “Starting From a GitHub Repository”Instead of an empty /work, a sandbox can start from a github.com repository. The service clones it;
nothing is uploaded from your machine:
Sandbox.create(source="github.com/acme/app", source_revision="") # "" = default branchawait Sandbox.create({ source: { url: "github.com/acme/app" } });sandbox.Create(ctx, &sandbox.CreateOptions{Source: &sandbox.GitSource{URL: "github.com/acme/app"}})Sandbox::create(CreateOptions { source: Some(GitSource { url: "github.com/acme/app".into(), revision: String::new() }), // "" = default branch ..Default::default()}).await?;- The result:
/workis a detached HEAD at the requested commit, with a bloblessoriginthat fetches through the session’s GitHub proxy. - Repository environments: if the repository has
.chainguard/develop.yamlorci.yaml, that environment is used. Your packages apply only when it has neither. - Not listed: these sandboxes aren’t in
Sandbox.list(), which only lists empty-workspace sandboxes; keep the ID.
