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.

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.

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
s0 sandbox create --template my-app

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 Providers#

Sandbox0 supports these manager-side registry credential providers:

External push and node/private pull endpoints may differ. Configure push_registry for developers and CI, pull_registry for manager's durable RootFS importer, and internal_registry for server-side registry operations when needed. Template image references use the pull address returned by the credential API.

Self-hosted registry credentials are direct manager configuration inputs. Each secret may be supplied by its documented value field or file field, but never both. The durable importer uses registry.pull_credentials_file, a root-owned Docker config.json/dockerconfigjson file, when the source registry requires static pull authentication.

yaml
registry:
    provider: builtin
    push_registry: registry.example.com
    pull_registry: registry.internal.example.com
    pull_credentials_file: /etc/sandbox0/registry/pull-config.json
    builtin:
        username_file: /etc/sandbox0/registry/push-username
        password_file: /etc/sandbox0/registry/push-password

The files must be readable by manager and must not be exposed to a sandbox. There is no per-allocation registry secret and no runtime-mounted registry credential.

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#