On Runtime, a Container runs any OCI image from any
registry, by tag or by digest, under Docker on a Linux machine of its own.
An image built with docker build is already one: Docker's image format and
the OCI format describe the same parts, and registries serve both.
The parts of an image
Every part is a blob stored by the SHA-256 digest of its bytes, so a part cannot change without its name changing too.
| Part | What it holds |
|---|---|
| Index | A list of manifests, one per platform, such as linux/amd64 and linux/arm64 |
| Manifest | The config's digest and the digests of the layers, in order |
| Config | The command to run, environment variables, the working directory, the platform |
| Layers | Compressed tar archives of files. Each one adds, changes or deletes files of the one below |
A runtime pulls the index, picks the manifest for its own platform, pulls the config and the layers it does not have yet, and stacks the layers into one filesystem. Layers are shared: two images built on the same base pull that base once.
The image specification sits beside two others. The distribution specification defines the HTTP API that registries serve, and the runtime specification defines how a container is started from an unpacked image. Version 1.1 of the image and distribution specifications, released in February 2024, added a way to attach artifacts such as signatures and SBOMs to an image.
Tags and digests
A tag such as nginx:stable is a name that its owner can move to a new image
at any time. A digest such as nginx@sha256:9090… names exactly one set of
bytes and never changes. Pin a digest where a change of image must be a
decision, as in production deploys.
This reads the index behind nginx:stable from Docker Hub with the
distribution API, and prints each platform's manifest digest:
Terminalrepo=library/nginxtag=stabletoken=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:$repo:pull" | jq -r .token)curl -s "https://registry-1.docker.io/v2/$repo/manifests/$tag" \ -H "Authorization: Bearer $token" \ -H "Accept: application/vnd.oci.image.index.v1+json" \ -H "Accept: application/vnd.docker.distribution.manifest.list.v2+json" | jq -r '.mediaType, (.manifests[] | "\(.platform.os)/\(.platform.architecture) \(.digest)")'# application/vnd.oci.image.index.v1+json# linux/amd64 sha256:...# unknown/unknown sha256:...An entry for unknown/unknown is not an image. It is an attestation manifest,
such as build provenance, which Docker BuildKit stores in the index beside the
images it describes.
Run an image by digest on Runtime
This runs traefik/whoami pinned to one digest and reads it through a
preview, with your key in RUNTIME_API_KEY:
Terminalapi=https://api.withruntime.com/v2auth="Authorization: Bearer $RUNTIME_API_KEY"image="traefik/whoami@sha256:1699d99cb4b9acc17f74ca670b3d8d0b7ba27c948b3445f0593b58ebece92f04"container=$(curl -sf -X POST "$api/containers" -H "$auth" -H "Content-Type: application/json" \ -d "{\"env\": {\"RUNTIME_CONTAINER_IMAGE\": \"$image\"}}" | jq -r .id)trap 'curl -sf -X DELETE "$api/containers/$container" -H "$auth" > /dev/null' EXITpreview=$(curl -sf -X POST "$api/sandboxes/$container/previews" -H "$auth" \ -H "Content-Type: application/json" -d '{"port": 80}')curl -sf --retry 60 --retry-all-errors --retry-delay 1 "$(jq -r .url <<< "$preview")" \ -H "x-runtime-preview-token: $(jq -r .token <<< "$preview")" | head -n 1# Hostname: ...To boot a whole Runtime machine from your own image instead of running it as a container, build an image from a Dockerfile.
Related
- How to deploy a Docker container
- What is a container?
- Docker vs virtual machine
- What is a platform as a service (PaaS)?
Sources
- OCI Image Format Specification, checked 17 November 2026
- OCI Image Manifest Specification, checked 17 November 2026
- OCI Distribution Specification, checked 17 November 2026
- OCI image-spec v1.1.0 release, checked 17 November 2026
- Docker Docs, Attestation storage, checked 17 November 2026
Facts on this page were checked on 17 November 2026.