Skip to content

Glossary

What is an OCI image?

An OCI image is a container image in the standard format of the Open Container Initiative: a manifest, a config and filesystem layers.

Updated · Facts checked · By Runtime Cloud

3 min read

Read as Markdown

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.

Sources

Facts on this page were checked on 17 November 2026.

Cut your cloud billby 66%.

7 days of Pro for $0, and no card to sign up. Billed by the second after.

Start your free trial