opencontainers/runtime-spec: the config file that every OCI runtime reads

What the runtime-spec actually standardises

The repository is a specification, not a runtime. Its README describes the Open Container Initiative as developing "specifications for standards on Operating System process and application containers", and the normative text lives in spec.md, with per-platform detail split across config-linux.md, config-freebsd.md, config-solaris.md, config-windows.md and config-zos.md. The audience is narrow and stated: application bundle builders, hook developers and runtime developers. If you are deploying an application, this is not your layer. If you are writing a runtime, a bundle generator or a lifecycle hook, it is the whole layer. The problem it solves is portability of the launch description. A bundle produced by one tool should be runnable by another implementation, because both agree on the file name, the directory layout and the meaning of each field. That agreement is what lets a Kubernetes node pick a runtime without the image builder knowing which one it picked.

Bundle layout and the host-specific fields in config.json

A bundle is a directory. It contains the OCI configuration file, named config.json, and the filesystem the container will see. The README's use-case section lists what a builder puts in that configuration: the executable to launch, mount locations, hook paths, Linux namespaces and cgroups. Note the split it draws. Some settings are host-independent, such as which executable to launch. Others are host-specific, and the README is explicit that "application bundle directories copied between two hosts may require configuration adjustments". That sentence is the most practically important one in the README, and it is easy to skim past. A bundle is not a portable artefact in the way an image is. The image is portable; the bundle is bound to the machine it was written for, because mount sources, namespace choices and cgroup paths refer to that machine. The features.md and features-linux.md files exist because implementations differ in what they support, so a config can be valid and still fail on a given runtime.

Building the specification docs and reading the Go types

There is nothing to install in the usual sense. The spec is consumed as documentation plus a Go module, specs-go, which holds the Go types for the configuration. The README points to spec.md for the normative text. The Makefile builds the documentation bundle, and it requires either pandoc or docker; without either, the build target fails with "cannot build $@ without either pandoc or docker".

To build the PDF and HTML versions of the specification locally:

make docs

The Makefile writes output/oci-runtime-spec.pdf and output/oci-runtime-spec.html, assembling the DOC_FILES list in a fixed order that starts with version.md and spec.md. If pandoc is absent but docker is present, the Makefile substitutes a pinned pandoc image, so the output does not depend on your local pandoc version. The version.md file itself is generated from specs-go/version.go by a tool under .tool/.

For Go consumers, the types live in specs-go. The Makefile's version target is the only Go invocation the repository files show:

go run ./.tool/version-doc.go > $@

That command regenerates version.md from specs-go/version.go. The decoded types in specs-go give you the process, mounts, hooks and platform sections as typed fields. The repository also carries a schema/ directory for validating a config.json against the specification, which is the check worth running before you hand a bundle to a runtime.

Where the specification stops and the runtime begins

The spec does not define how a container is created, only what the request looks like. It says nothing about the lifecycle commands a runtime exposes, how images are pulled, or how storage is managed. Those live elsewhere: image handling in the image-spec and distribution-spec, orchestration in the Container Runtime Interface. A common mistake is to expect the runtime-spec to answer questions about running containers, when it only answers questions about describing them. There is a second boundary worth naming. The README states that before a nontrivial change to the specification you should mail the mailing list, and that "a GitHub pull-request is not the place for high-level discussions". For anyone considering contributing, that is a real process constraint rather than a formality: design debate happens on the list, and pull requests are for typos and grammatical errors.

Alternatives and how their approach differs

The nearest alternative is not a competitor but a different layer: the OCI Image Specification. The image-spec describes the artefact you distribute, layers and manifests; the runtime-spec describes how a local runtime launches a process from an unpacked bundle. A registry speaks the distribution-spec, an image builder speaks the image-spec, and the runtime speaks the runtime-spec. Choosing between them is not a choice, it is a pipeline. If your actual question is how to run containers without writing a runtime, the answer is an implementation listed in implementations.md, such as runc, or a higher-level system like Docker or CRI-O that sits above one. Those projects consume this specification. They also add behaviour the specification deliberately leaves open, which is why two conformant runtimes can still differ in defaults and error messages.

Maintenance, releases and the cost of tracking the spec

The repository is not archived, and the last push was on 2026-04-24. Releases are infrequent by design: v1.2.0 on 2024-02-13, v1.2.1 on 2025-02-27 and v1.3.0 on 2025-11-04. That cadence is a feature for implementers, since a specification that changes weekly is unusable, but it also means a field you need may sit unreleased for a year or more. Upgrade cost falls mostly on runtime authors. When a new version lands, an implementation has to decide whether to claim support for it, and consumers of that implementation have to check the claim. The repository ships RELEASES.md and a ChangeLog, which are the places to look for what moved between versions. The licence is Apache-2.0, stated in the README and in the LICENSE file. That is a permissive licence, and it governs the specification text and the code in this repository; it says nothing about the licence of any runtime that implements the spec, which you have to check separately. Nothing here is legal advice.

Who should read it and what to check first

Read this repository if you are writing a runtime, generating bundles, or writing lifecycle hooks that need to behave consistently across implementations. Do not read it if your goal is to run a container; the README's own use-case list does not include that audience, and implementations.md already points you at software that does the work. The first thing to check is not the prose but the schema/ directory and the version your target runtime claims, because a config that validates against a newer schema may still be rejected by a runtime built against an older one. The second is the host-specific warning: if you plan to move bundles between machines, plan for the mount and namespace sections to need rewriting, not just copying.

Editorial conclusion

Runtime authors, bundle builders and hook developers should treat this repository as the contract their code is checked against, and start from spec.md plus the schema/ directory rather than from a runtime's defaults. Teams that only want to run containers should not read it at all; runc, CRI-O or Docker already implement it. Before adopting anything built on it, verify which spec version the implementation claims, since v1.3.0 landed on 2025-11-04 and older runtimes will not know newer fields.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. opencontainers/runtime-spec on GitHub
3. Project website
4. README
5. Releases