NewCompare CPU & GPU pricing across AWS, Azure & GCP
Self-hosted sandboxes

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

RequirementWhy
linux/amd64DevZero 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 userSandboxes 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 CMDsandboxd 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 setsidThe 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 /workspaceUnder 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 registryThe 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.

ImageBuilt onContainsFor
sandbox-base:1debian:bookworm-slimsandboxd, ca-certificates, curl, git, bash, coreutils, procps, user sandbox (uid 1000), /workspace owned by uid 1000, C.UTF-8 localethe default image
sandbox-python:3.12sandbox-basePython 3.12, uv, a virtualenv at /opt/venv with requests, numpy, pandascode-interpreter agents
sandbox-node:22sandbox-baseNode 22, pnpmJavaScript and TypeScript agents
sandbox-agent-toolkit:1sandbox-pythonNode 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.allowedRegistries must stay within it, and its image.default must match both lists. A policy with an empty image.allowedRegistries is 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: false

A 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/AmazonEC2ContainerRegistryReadOnly

For 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.

  1. Find the digest your operator release expects. It is the sandboxd-inject init container image in the policy's SandboxTemplate (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 condition SandboxdImageUnreachable: True when the injector cannot be reached or found (InjectorRegistryUnreachable, InjectorManifestNotFound) or the mirror has the wrong digest (InjectorDigestMismatch), and Unknown when 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}'
  2. Copy the image by digest, preserving it. crane and skopeo copy manifests byte for byte:

    crane copy \
      public.ecr.aws/devzeroinc/sandboxd@sha256:<digest> \
      registry.acme.internal/devzeroinc/sandboxd@sha256:<digest>
  3. 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 reasonMeaningWhat to do
ImagePullFailedthe image does not exist, or the node cannot authenticate to the registrycheck the reference; grant node identity or add a pull Secret
ImageArchUnsupportedthe image has no linux/amd64 variant (kubelet: no match for platform)publish an amd64 image
SandboxdInjectFailedthe init container could not copy sandboxdusually transient; the pod is retried per the policy's failedPodPolicy
OverrideRejectedan override did not pass the final pod checkcompare the requested image and resources with the policy
Policy condition SandboxdImageUnreachable=Truethe operator cannot find the injector image in its registry, or the mirror has the wrong digestallow public.ecr.aws or mirror the injector with the expected digest

On this page