Open Container Initiative (OCI) specifications

Three vendor-neutral standards that let any build tool, registry and runtime share containers: how a runtime starts one, how an image is laid out, and the HTTP API registries use to push and pull it.

Linux Foundation project

What it is: Containers
Used for: Artifact registries
Type: Open source
Made by: Open Container Initiative (Linux Foundation), founded by Docker, CoreOS and others
Foundation: The Linux Foundation, joined June 2015. Published by the Open Container Initiative, an LF project run by its own Technical Oversight Board
License: Apache 2.0
Facts checked: 28 October 2026

What it is

The Open Container Initiative maintains three specifications. The Runtime Specification starts from a filesystem bundle, a directory holding a root filesystem and a config.json that sets the process, mounts, namespaces, cgroups and other limits, and defines the operations every runtime must offer: create, start, kill, delete and state, with hooks at fixed points in between. It covers Linux, Windows, Solaris, z/OS and, since version 1.3 in November 2025, FreeBSD, plus a vm section for runtimes that start a virtual machine. The Image Specification describes what a builder produces: an image index lists one manifest per platform, and each manifest points to a configuration (environment, entry point, layer order) and a list of layers, tar archives of filesystem changes. Each reference is a descriptor carrying a media type, a size and a digest, so every piece is named by its hash and verified on arrival. The Distribution Specification, based on Docker’s Registry HTTP API V2, defines the /v2/ endpoints for pulling manifests and blobs by tag or digest, uploading blobs then manifests, listing tags, deleting, and mounting a blob from another repository.

Because the formats are shared, the pieces are interchangeable: an image built by Docker or Podman can be stored in Harbor, Quay or a cloud registry and started by runc, crun, youki, gVisor’s runsc or Kata Containers, all listed as runtime-spec implementations. Version 1.1 of the image and distribution specs, in February 2024, made registries general content stores. Any file can be pushed as an artifact, an ordinary image manifest with an artifactType field, and a subject field points one manifest at another, so a signature, SBOM or attestation can be attached to an image. The new referrers API (GET /v2/<name>/referrers/<digest>) lists what points at an image. The OCI also hosts runc, the reference runtime. A Technical Oversight Board, in 2026 with members from Microsoft, IBM, Docker, AWS, Google and others, settles cross-project issues and decides which projects the OCI takes on.

Why teams pick it

Build, store and run are decoupled: any conforming builder, registry and runtime work together, so switching one doesn’t mean rebuilding images
Everything is content-addressed: a digest names exact bytes, so pulls are verifiable and identical layers are stored and transferred once
Registries carry more than images: since 1.1, Helm charts, signatures, SBOMs and other artifacts sit next to the image they describe, found through the referrers API
Vendor-neutral: maintained in the open under the Linux Foundation, overseen by a board drawn from competing companies

Watch out for

They cover formats and interfaces only: how an image is built (a Dockerfile, for example), how containers are networked and how they are orchestrated are outside the OCI’s scope
Referrers support is uneven: clients must fall back to a tag scheme (sha256-<digest>) on older registries, which the OCI notes is open to race conditions and clutters tag lists
Slow, consensus-driven change: the image spec went from 1.0 in July 2017 to 1.1 in February 2024, and a dedicated artifact manifest was dropped before 1.1 over portability concerns
Docker’s heritage still shows: the distribution spec warns clients may meet Docker-specific headers and error codes, and older Docker manifest media types remain in use

Alternatives

What all containers have in common →Compare side by side →

AWS FargateAWSRuns ECS tasks and EKS pods without servers: you size each task, AWS finds the machine.

Cloudflare ContainersCommercialLinux container images that run on Cloudflare’s network next to a Worker, each instance started on demand by its own Durable Object and put to sleep when idle.+1 Cloudflare Sandbox SDK

DockerOpen sourceThe tool that made containers mainstream: build an image from a Dockerfile, then run it anywhere.

Google Cloud RunGoogle CloudGive Google a container that listens on a port; it runs as many copies as traffic needs, down to zero.

gVisorOpen sourceA Linux kernel reimplemented in Go that runs in user space, so a container’s system calls never reach the host kernel directly.

PodmanOpen sourceRuns Docker-style containers without a daemon, as root or as an ordinary user, and hands long-running ones to systemd.

runcOpen sourceThe reference OCI runtime: a small Linux command-line tool that turns a bundle into a running container, and the default runtime underneath containerd and Docker Engine.

How it fits with other technologies

What Open Container Initiative (OCI) specifications uses

What uses Open Container Initiative (OCI) specifications

runcis the reference implementation ofOpen Container Initiative (OCI) specificationsContainers

An OCI image manifest: one config and one layer, each named by its digest (illustrative values) · json

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "digest": "sha256:b5b2b2c507a0944348e0303114d8d93aaaa081732b86451d9bce1f432a537bc7",
    "size": 7023
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:9834876dcfb05cb167a5c24953eba58c4ac89b1adf57f28f2f9d09af107ee8f0",
      "size": 32654
    }
  ],
  "annotations": {
    "org.opencontainers.image.source": "https://github.com/example/api"
  }
}

The three specifications#

Each is versioned on its own, and tools state which versions they support.

Specification	What it defines	1.0	Latest release
Runtime	A bundle (`config.json` plus root filesystem), the container lifecycle and its hooks, per platform	July 2017	1.3.0, November 2025: adds FreeBSD, network devices and VM hardware settings
Image	Image index, manifest, configuration and layers, all linked by content descriptors	July 2017	1.1.1, March 2025; 1.1.0 (February 2024) added `artifactType`, `subject` and zstd layers
Distribution	The `/v2/` registry API for pushing, pulling, tagging, deleting and finding referrers	May 2021	1.1.1, January 2025; 1.1.0 (February 2024) added the referrers API

A signature attached to an image#

Since 1.1 an artifact is an image manifest with an artifactType. With no configuration to carry, it points at the standard two-byte empty descriptor ({}), and subject ties it to the image it signs. A registry returns it from GET /v2/<name>/referrers/<image digest>. Illustrative values.

json

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "artifactType": "application/vnd.dev.sigstore.bundle.v0.3+json",
  "config": {
    "mediaType": "application/vnd.oci.empty.v1+json",
    "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
    "size": 2
  },
  "layers": [
    { "mediaType": "application/vnd.dev.sigstore.bundle.v0.3+json", "digest": "sha256:…", "size": 4812 }
  ],
  "subject": {
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "digest": "sha256:…",
    "size": 1024
  }
}

See it in a real stack

No architecture uses Open Container Initiative (OCI) specifications yet. Drop it into the playground and wire it up yourself.Open playground →

Where it came from2015–2025

By 2015 Docker’s image format and runtime had become the de facto way to package software, and the company controlled both. CoreOS had answered with its own runtime, rkt, and an alternative image spec, appc, and the rift worried companies building on containers. On June 22, 2015, at DockerCon in San Francisco, Docker, CoreOS and others announced the Open Container Project under the Linux Foundation; the founding members included AWS, Google, IBM, Intel, Microsoft, Red Hat and VMware. Docker donated its container format and its runtime, runC, as the starting point, and appc’s maintainers joined in.

Runtime Specification 1.0 and Image Format Specification 1.0 were released on July 19, 2017. The image format took ideas from both appc and Docker’s v2.2 image format, while signing and the transport of images over an API were left for later. The Distribution Specification, based on Docker’s Registry HTTP API V2, reached 1.0 on May 5, 2021.

Supply-chain security drove the next change. Signatures and SBOMs needed a home next to the images they describe, and tools had been storing them under special tag names. Image and Distribution 1.1, released on February 15, 2024, added artifacts, the subject field and the referrers API. Runtime 1.3 followed in November 2025, adding FreeBSD as a platform.

Why it’s built this way

Start from Docker’s code and formats: A standard that broke existing images would not have been adopted. Docker donated its runtime and format, and the image format was designed to stay compatible with Docker’s and appc’s, so existing tools could adopt it.
Name every piece by its digest: Manifests, configurations and layers are referenced by descriptors carrying a hash, so a client can check what it downloaded, identical layers are shared, and an image reference by digest can never change underneath you.
Reuse the image manifest for artifacts: The 1.1 release candidates had a separate artifact manifest, but it was removed because registries and clients that only understood image manifests could not store or copy it. An image manifest with an artifactType works with existing registries.

Timeline

2015
Open Container Project announced at DockerCon; Docker donates runC (June 22)
2017
Runtime and Image Specifications 1.0 released (July 19)
2021
Distribution Specification 1.0 released (May 5)
2024
Image and Distribution 1.1 add artifacts and the referrers API (February 15)
2025
Runtime Specification 1.3 adds FreeBSD (November 4)

Sources14 · facts checked 28 October 2026

Improve this page on GitHub