Skip to content

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.

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 create with 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 add at run time needs apk-tools in 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.

Outbound traffic is open by default (egress = ["*"]). Narrow it with an allowlist of hostnames:

Sandbox.create(egress=["pypi.org", "files.pythonhosted.org"])
  • Verified live: with egress: [example.com], https://example.com answered 200 and https://www.wikipedia.org was refused.
  • egress=[] allows no hosts.
  • egress_policy / egressPolicy / EgressPolicy decides 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.

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: 1
environment:
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.

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 branch
  • The result: /work is a detached HEAD at the requested commit, with a blobless origin that fetches through the session’s GitHub proxy.
  • Repository environments: if the repository has .chainguard/develop.yaml or ci.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.