Custom Images

Every image-based template names a normalized, SHA-256 digest-pinned OCI image. Sandbox0 accepts public images and team-scoped private images and imports their RootFS into the regional block store before runtime use. Mutable tags are rejected rather than resolved during template creation.

The Nomad task driver does not pull the template image. Manager's durable OCI importer authenticates to the registry, unpacks the digest-pinned RootFS, injects the pinned procd artifact, builds the block artifact, and publishes it to the regional S3-compatible RootFS store.

An image supplies filesystem contents, not a Docker startup contract. Sandbox0 starts procd as sandbox root; it does not run the image's ENTRYPOINT or CMD, adopt its USER or WORKDIR, or automatically copy its image-config environment into the template. Put required environment defaults in spec.envVars and explicitly set each command or service's working directory and startup command. Files created by Dockerfile RUN and COPY instructions remain part of the imported RootFS.

Public Images#

Reference a public image by its canonical registry, repository, and digest:

yaml
spec:
    mainContainer:
        image: docker.io/library/python@sha256:<64-hex-digest>
        resources:
            memory: 2Gi

The name must already be normalized. For example, use docker.io/library/python@sha256:..., not the Docker shorthand python@.... A registry tag change therefore cannot alter either a queued import or an already committed RootFS generation.

Private Image Workflow#

When you have a Dockerfile or another reproducible build, use the s0 CLI.

1. Build#

bash
s0 template image build . -t my-app:v1.2.3

This command wraps the local Docker build. You can also use docker build directly. Build for the Linux architecture required by your region, using --platform when it differs from your local Docker default, for example --platform linux/amd64. A single-platform image cannot satisfy an import for a different architecture; deployments with multiple required platforms need an image index containing those platforms.

2. Push#

bash
s0 template image push my-app:v1.2.3 -t my-app:v1.2.3

The CLI:

1. calls POST /api/v1/registry/credentials;
2. receives a provider-specific, team-scoped destination and credential;
3. retags the local image; and
4. pushes with the local Docker daemon.

Use the returned Template image reference rather than reconstructing a provider path yourself.

Resolve that pushed reference to the registry-reported manifest digest and replace its tag with @sha256:<digest>. Keep the exact pull hostname returned by Sandbox0; push and manager-side pull endpoints may differ. Standard registry tools such as docker buildx imagetools inspect or skopeo inspect can report the manifest digest.

3. Create The Template#

yaml
# template.yaml
spec:
    mainContainer:
        image: registry.example.com/t-<team-key>/my-app@sha256:<64-hex-digest>
        resources:
            memory: 8Gi

bash
s0 template create --id my-app --spec-file template.yaml

Replace the example registry path and digest with the actual pushed pull reference. Template creation validates the source and starts asynchronous import discovery; 201 Created is not proof that imports are ready. Claim after the required imports are ready:

bash
s0 sandbox create --template my-app

While import is pending, claim can return data_plane_not_ready. Inspect import failures through your platform operator instead of repeatedly creating another template with the same ID. The image's OCI-config defaults are not substitutes for explicit template environment and service configuration.

If the desired environment already exists in a sandbox, use /api/v1/templates/from-sandbox instead. That route retains the sandbox's immutable block-COW generation and does not require a new image push.

Registry Access#

Sandbox0 Cloud manages registry providers, authentication, and image import. Use the short-lived, team-scoped push credentials returned by the API and the pull image reference returned after push. Push and runtime pull hostnames may differ; do not reconstruct the pull address from the push address.

Registry backend configuration and credentials are platform operations, not settings supplied in a template or exposed to a sandbox. See Deployment Options for current service availability.

Import Safety#

The durable importer is active-active across manager replicas. PostgreSQL leases exactly one builder for an import attempt. Publication uses conditional object creation and compare-and-swap state transitions so retries cannot silently replace a committed artifact.

The importer validates:

• canonical OCI digest and target platform;
• bounded layer count and unpacked size;
• the pinned procd digest and protocol;
• the block filesystem artifact; and
• conditional publication to the configured RootFS object store.

An unavailable registry or failed import leaves the sandbox creation operation unready or failed; the task driver never falls back to pulling and running an unattested tag.

Next Steps#