Sandbox environments
A SandboxEnv binds one template, carries the settings every sandbox in it shares, and is the name you create sandboxes with.
A SandboxEnv is the addressable unit: the name you pass to
Sandbox.create(), the thing the console shows a page for, and the object
that binds exactly one template.
sbx = Sandbox.create("YOUR_ENV", timeout=3000, secure=False)An env is one class of runtime — "the E2B sandboxes for this team", "the Docker-in-Docker ones for this evaluation" — and it fans out to member pools that hold the actual capacity. It holds no Pods itself.
What an env owns
These are the settings every sandbox claimed from the env inherits:
| Setting | What it does |
|---|---|
overrides.image | replaces the template's main container image for every member pool |
overrides.podCreationImagePolicy | whether a new Pod starts on the template's image or on the idle image |
overrides.defaultStartupTimeout | how long a claim waits for the sandbox to become ready, when it does not say |
overrides.defaultIdleTimeout | how long an untouched sandbox lives before it is reclaimed, when it does not say |
overrides.imagePullSecret | credentials for a private registry, materialised into a Secret the member pools reference |
overrides.gateway | the switch that gives the env's Pods an egress sidecar — see egress and secrets |
overrides.volumes | PersistentVolumeClaims mounted into every sandbox |
overrides.updateStrategy | autoUpdate and maxUnavailable for rollouts |
labels, annotations | metadata stamped on the env and its member pools |
Changing most of these changes the Pod spec, and a changed Pod spec means the env's pools roll: existing idle Pods are replaced, one rollout at a time, and running sandboxes are left alone until they are returned.
Mode
| Mode | Behaviour |
|---|---|
WarmPool | claims are served from the env's member pools. This is what the platform runs. |
OnDemandJob | reserved: accepted by the API enum, not implemented by the controller. Do not build on it. |
The name goes everywhere
An env name is an RFC 1123 DNS label, capped at 24 characters because pool and
Pod names are derived from it (POOL = ENV + resourceKey (+ quotaShort),
POD = POOL + uuid) and those have to stay inside the 63-character limit.
The same name is the env in the E2B SDK, the console URL, and abx. Create the
same-named env in two clusters and they federate —
cross-cluster.
Reading and writing one
abx envs --cluster YOUR_CLUSTER # every env on the cluster
abx envs YOUR_ENV --cluster YOUR_CLUSTER # one env: template, mode, pools, sizing rule
# the safe way to change one
abx envs YOUR_ENV --editable --cluster YOUR_CLUSTER > env.json
# edit env.json
abx update envs YOUR_ENV -f env.json --cluster YOUR_CLUSTERabx create envs --help prints the whole body, field by field. Two things
about it are worth knowing before you edit a file:
- A write is a PUT. A field you leave out is a field you are asking to
remove, and
overridesis replaced wholesale. imagePullSecretcannot be read back.GETreportsimagePullSecretConfiguredinstead of the credentials, and that flag is also the only way to say "keep them": a PUT carrying neither the secret nor the flag is asking for the stored credentials to be deleted. Editing an unrelated setting with a file that dropped the flag revokes your registry access.
The registry credentials are one flag away from being deleted
--editable prints imagePullSecretConfigured: true, not the secret. Send that
file back unchanged and the credentials survive. Strip the flag while editing
something else and the PUT means "delete them" — the next image pull fails, and
nothing in the response says why.
Common misconceptions
- "The env is a namespace." It is not; the namespace comes from your team. An env is a runtime identity plus its settings.
- "An env holds capacity." Pools do. An env with no member pool has no sandboxes to hand out, however it is configured.
- "I can repoint an env at another template."
templateRefis fixed at create. Moving runtimes means creating an env on the new template and moving traffic.
See also
- Pools — where the capacity is
- Autoscaling — the size of that capacity over time
- Egress and secrets — the env's gateway switch