For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

DigitalOcean Container Registry (DOCR) supports pushing SOCI-enabled images to your registry. A Seekable OCI (SOCI) index lets SOCI-aware container runtimes start containers in seconds by streaming image layers on demand instead of downloading the entire image first. This is especially useful for large images, such as AI and machine learning images that are several gigabytes in size.

SOCI v2 works by converting an existing image into a SOCI-enabled image with the index built in. The converted image is still a standard OCI image: runtimes without SOCI support, such as plain Docker, pull and run it as a normal image, while SOCI-aware runtimes get lazy loading.

There are two ways to create and push a SOCI-enabled image. The standalone workflow uses skopeo and the soci CLI and does not require containerd, so it works on any machine, including CI runners and build hosts. The containerd workflow uses nerdctl on a host that is already set up with the SOCI snapshotter.

Prerequisites

• A container registry.
• A personal access token with registry read and write access.
• For the standalone workflow: skopeo and the soci CLI version 0.13 or later.
• For the containerd workflow: a host with nerdctl and the SOCI snapshotter installed.

Pushed images are subject to the Container Registry limits on image and layer size.

Convert and Push an Image Using skopeo

The standalone workflow copies the source image to a local directory, converts it, and pushes the result without requiring a container runtime on the machine.

First, copy the source image into a local OCI layout directory:

skopeo copy docker://<source-image>:<tag> oci:./src-dir:<tag>

Then, convert the image into a SOCI-enabled image:

soci convert --standalone --format oci-dir ./src-dir ./out-dir

The --standalone flag builds the SOCI index without requiring a containerd content store, and --format oci-dir writes the converted image to a local OCI layout directory.

Finally, push the converted image to your registry. skopeo authenticates with your personal access token as both the username and the password:

skopeo copy --dest-creds "<your-api-token>:<your-api-token>" \
  oci:./out-dir:<tag> \
  docker://registry.digitalocean.com/<your-registry>/<image>:<tag>

Convert and Push an Image Using nerdctl

On a containerd host with nerdctl and the SOCI snapshotter installed, you can convert and push without an intermediate directory.

First, log in to the registry with your personal access token as both the username and the password, then pull the source image:

nerdctl login registry.digitalocean.com -u <your-api-token> -p <your-api-token>
nerdctl pull <source-image>:<tag>

Then, convert the image and tag it with its destination path in your registry:

soci convert <source-image>:<tag> registry.digitalocean.com/<your-registry>/<image>:<tag>

Finally, push the converted image:

nerdctl push registry.digitalocean.com/<your-registry>/<image>:<tag>

Pull Behavior of SOCI-Enabled Images

Because a SOCI-enabled image is a standard OCI image, anyone with access to your registry can pull it with Docker or any other OCI-compatible tooling and get a normal, full-download image. Hosts that run a SOCI-aware runtime, such as nerdctl with the SOCI snapshotter, get lazy loading automatically. To set up a host for lazy pulls, see How to Pull AI Images from DOCR Mirror Registries.