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

<Callout variant="info">
If a template runs [Sandbox Functions](/docs/sandbox/functions), its image must
include `python3` in `PATH` and use Python 3.9 or later. Sandbox0 injects the
function runner, but the runner uses the template's Python interpreter.
</Callout>

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](/docs/sandbox/deployment) 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

<CardGroup>
  <Card title="Template Configuration" href="/docs/sandbox/template/configuration" cta="Continue">
    Configure image, resources, environment, and network defaults.
  </Card>
  <Card title="Create From A Sandbox" href="/docs/sandbox/template#create-from-a-sandbox" cta="Continue">
    Reuse an initialized block-COW RootFS without publishing an image layer.
  </Card>
</CardGroup>