Sandbox images
What a sandbox image needs, which DevZero base images exist, how registry allowlists and guardrails work, cloud registry auth, mirroring the sandboxd injector, and why an image override is a cold start.
Sandbox images
A sandbox can run any image from a registry its policy allows. You do not need to rebuild your images for DevZero: every sandbox pod gets the sandbox daemon, sandboxd, copied in by an init container, and sandboxd runs your commands inside your image's filesystem, with your toolchain. DevZero's base images are a convenient starting point, not a requirement.
Image requirements
| Requirement | Why |
|---|---|
| linux/amd64 | DevZero gVisor node pools are amd64 only, and so are sandboxd and the base images. An arm64-only image fails at pull time with reason ImageArchUnsupported. |
| Works as a non-root user | Sandboxes run as uid 1000 by default, whatever the image's USER says. Root (uid 0) is never allowed. Make sure the files your tools write to are writable by uid 1000; /workspace always is. |
Does not rely on ENTRYPOINT or CMD | sandboxd is the container's main process. Your image's ENTRYPOINT and CMD are not executed. Nothing runs until a client starts a command (see below). |
Has /bin/sh and setsid | The Python SDK starts background commands (background=True) with setsid from a shell, so they outlive the connection that started them. busybox or util-linux provides setsid; the DevZero base images have both. Without it a background command stops when the SDK's connection closes; foreground commands, files and the terminal do not need it. |
Writes large files to /workspace | Under gVisor the root filesystem overlay is held in memory: anything written outside /workspace and /tmp counts against the sandbox's memory limit. /workspace is a persistent volume (10Gi by default) and /tmp is a sized scratch volume. |
| Comes from an allowed registry | The image must match the policy's registry list, which itself must be within the cluster guardrails. See Registry allowlists. |
Your image's ENTRYPOINT and CMD do not run
sandboxd runs as the container's first process and starts nothing on its own. Commands run when a client calls them (commands.run(...) in the SDK, /v1/exec on the gateway). They inherit the image's environment variables. An image whose CMD starts a web server will not start that server by itself; start it as a background command after the sandbox is ready:
sb = dz.sandboxes.create(policy="default", cluster_id="<cluster>")
sb.commands.run("python -m http.server 8000", background=True)Automatically running a configured entrypoint arrives in Phase 2 (image.runEntrypoint).
Commands share sandboxd's user and environment, including the policy's env and envFrom values. Environment variables a client should read through sandboxd's metadata endpoint must start with SANDBOX_.
DevZero base images
Published to public.ecr.aws/devzeroinc/ (canonical) and mirrored to docker.io/devzeroinc/, linux/amd64, rebuilt for base OS fixes (checked monthly) and whenever DevZero updates sandboxd.
| Image | Built on | Contains | For |
|---|---|---|---|
sandbox-base:1 | debian:bookworm-slim | sandboxd, ca-certificates, curl, git, bash, coreutils, procps, user sandbox (uid 1000), /workspace owned by uid 1000, C.UTF-8 locale | the default image |
sandbox-python:3.12 | sandbox-base | Python 3.12, uv, a virtualenv at /opt/venv with requests, numpy, pandas | code-interpreter agents |
sandbox-node:22 | sandbox-base | Node 22, pnpm | JavaScript and TypeScript agents |
sandbox-agent-toolkit:1 | sandbox-python | Node 22, gh, ripgrep, jq, build-essential (no Docker CLI: Docker-in-Docker does not run under gVisor) | coding-agent CLIs |
Each image has a moving tag (as above; there is never a latest tag) and an immutable dated tag that names the runtime, build date and sandboxd version, such as sandbox-python:3.12-20261201-sandboxdv1.0.11. For reproducible sandboxes, pin by digest.
DevZero sandbox images are not yet signed and ship without SBOMs. This will follow a DevZero-wide decision on image signing. Digest pinning, enforced at admission, is available today.
How sandboxd gets into your image
Every sandbox pod has an init container that copies a pinned, statically linked sandboxd binary into a small shared volume at /opt/devzero/bin. The sandbox container then runs /opt/devzero/bin/sandboxd as its command. This happens for every image, including DevZero's base images (their own copy of sandboxd is hidden by the volume), so every sandbox in a release runs the same sandboxd version. There is no opt-out.
The injector image is public.ecr.aws/devzeroinc/sandboxd, referenced by digest. The pod admission webhook rejects any sandbox pod with an init container that is not this exact image, so a sandbox pod cannot run other init containers. Copying the binary adds roughly half a second to a cold start; warm pools hide it.
Registry allowlists and guardrails
Registries are checked at two levels:
- the cluster guardrails'
allowedRegistries, set by a team Admin, is the ceiling for every policy. The default guardrails allow every registry ("*") until an Admin narrows them; - each policy's
image.allowedRegistriesmust stay within it, and itsimage.defaultmust match both lists. A policy with an emptyimage.allowedRegistriesis bounded by the guardrails alone, but cannot allow image overrides.
# Guardrails (cluster-wide ceiling)
allowedRegistries:
- "public.ecr.aws/devzeroinc/"
- "123456789012.dkr.ecr.us-east-1.amazonaws.com/"
---
# A policy
image:
default: public.ecr.aws/devzeroinc/sandbox-python:3.12
allowedRegistries:
- "public.ecr.aws/devzeroinc/" # DevZero base images
- "123456789012.dkr.ecr.us-east-1.amazonaws.com/ml-sandboxes/" # one path in your ECR
allowOverride: true
requireDigest: falseA policy listing a prefix the guardrails do not cover is not applied: it reports WithinGuardrails=False with reason ExceedsClusterGuardrails.
How matching works. References are normalized first: python:3.12 becomes docker.io/library/python:3.12, and registry and repository names are lower-cased. A prefix matches on a path boundary, never in the middle of a name. End an organization or path prefix with /: public.ecr.aws/devzeroinc/ matches every image under that organization. A prefix without the trailing / names one repository and the paths under it: docker.io/library/python matches python:3.12 but not pythonista. DevZero warns when a prefix has no trailing / and looks like an organization rather than a repository. A prefix cannot contain a tag or a digest, and the only wildcard is the single entry "*", which allows every registry.
Where it is checked. When a policy is saved, when a sandbox is requested through the API (the error lists the allowed prefixes), when a claim is admitted, and when the pod is admitted. The pod check covers every container, and every init container must be the pinned sandboxd injector, so a sandbox object edited behind DevZero's back still cannot run a disallowed image. Images cannot be changed on a running sandbox pod.
requireDigest: true rejects tag references everywhere: in the default image, in overrides, and in every container. Use image@sha256:… references.
Pulling from private registries
Cloud registries through node identity
On a DevZero gVisor pool, the kubelet pulls with the node's cloud identity, so ECR, ACR and Artifact Registry need no pull Secret. Grant the sandbox node policy's identity read access:
Attach the AWS managed policy AmazonEC2ContainerRegistryReadOnly to the node role named in the node policy (aws.role), for example KarpenterNodeRole-my-cluster:
aws iam attach-role-policy \
--role-name KarpenterNodeRole-my-cluster \
--policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnlyFor a registry in another account, also allow the node role in that repository's policy.
Other registries: pull Secrets
List pull Secrets in the policy's image.imagePullSecrets. They must exist in the policy's namespace (devzero-sandbox by default); a missing one shows as ImagePullSecretsReady=False. DevZero never copies pull Secrets between namespaces in Phase 1.
Mirroring the sandboxd injector
If your cluster cannot pull from public.ecr.aws (air-gapped, or an egress allowlist), copy the injector image into your own registry and point the policy at the copy with image.sandboxdImage. The copy must keep the same digest: a mirror with any other digest is rejected.
-
Find the digest your operator release expects. It is the
sandboxd-injectinit container image in the policy'sSandboxTemplate(named after the policy, in its namespace). The operator checks, without credentials, that it can find the injector in its registry, and reports the result on each policy as the conditionSandboxdImageUnreachable:Truewhen the injector cannot be reached or found (InjectorRegistryUnreachable,InjectorManifestNotFound) or the mirror has the wrong digest (InjectorDigestMismatch), andUnknownwhen the registry requires credentials or rate-limits the check (InjectorRegistryAuthRequired,InjectorRegistryRateLimited), since only the nodes hold pull credentials.kubectl -n devzero-sandbox get sandboxtemplate default \ -o jsonpath='{.spec.podTemplate.spec.initContainers[?(@.name=="sandboxd-inject")].image}' -
Copy the image by digest, preserving it.
craneandskopeocopy manifests byte for byte:crane copy \ public.ecr.aws/devzeroinc/sandboxd@sha256:<digest> \ registry.acme.internal/devzeroinc/sandboxd@sha256:<digest> -
Set the mirror on the policy, by digest, and add the mirror's registry to the policy's and the guardrails' allowlists. Keep the prefixes that cover
image.default, or the policy is rejected:image: default: registry.acme.internal/devzeroinc/sandbox-python:3.12 # base image mirrored too, if public.ecr.aws is unreachable sandboxdImage: registry.acme.internal/devzeroinc/sandboxd@sha256:<digest> allowedRegistries: - "registry.acme.internal/devzeroinc/" # the mirror: covers both the default image and the injector
When DevZero upgrades sandboxd, the expected digest changes; mirror the new one before upgrading the operator.
Overrides are cold starts
If a policy sets image.allowOverride: true, a caller can ask for a different image (from the allowed registries) and for different resources (up to the policy's resources.max) for one sandbox:
sb = dz.sandboxes.create(
policy="default",
cluster_id="<cluster>",
image="public.ecr.aws/devzeroinc/sandbox-python:3.12",
resources={"cpu": "2", "memory": "4Gi"},
)In-cluster callers do the same with two environment entries on their SandboxClaim, the only ones a claim may carry:
spec:
warmPoolRef: { name: default }
env:
- { name: DEVZERO_OVERRIDE_IMAGE, value: "public.ecr.aws/devzeroinc/sandbox-python:3.12" }
- { name: DEVZERO_OVERRIDE_RESOURCES, value: '{"cpu":"2","memory":"4Gi"}' }An override always starts a new pod from scratch. It never uses a warm pod. It pays the full cold-start time: image pull, gVisor boot and possibly a new node. If you need fast starts on a second image, create a second policy with that image as its default and its own warm pool. One policy has exactly one warm pool.
A claim carrying any other environment variable is refused with EnvNotAllowed; names starting with DEVZERO_, SANDBOX_ or LD_, and PATH, can never be set by callers. Other refusals: OverrideNotAllowed (the policy does not allow overrides), ImageNotAllowed (the message lists the allowed prefixes) and ResourcesExceedMax.
When an image fails
| Sandbox status reason | Meaning | What to do |
|---|---|---|
ImagePullFailed | the image does not exist, or the node cannot authenticate to the registry | check the reference; grant node identity or add a pull Secret |
ImageArchUnsupported | the image has no linux/amd64 variant (kubelet: no match for platform) | publish an amd64 image |
SandboxdInjectFailed | the init container could not copy sandboxd | usually transient; the pod is retried per the policy's failedPodPolicy |
OverrideRejected | an override did not pass the final pod check | compare the requested image and resources with the policy |
Policy condition SandboxdImageUnreachable=True | the operator cannot find the injector image in its registry, or the mirror has the wrong digest | allow public.ecr.aws or mirror the injector with the expected digest |
Exposure modes
How agents outside your cluster reach sandboxes, what each exposure mode sends through DevZero, who holds the DNS name, certificate and key, and how to fix a failed setup.
Trust and data disclosure
What the DevZero control plane can do inside your cluster, what caps it, what it can never do, and exactly which data leaves the cluster.