Introduction

Introduction

Registries are evolving as generic artifact stores. To enable this goal, the ORAS project provides a way to push and pull OCI Artifacts to and from OCI Registries.

Users seeking a generic registry client can benefit from the ORAS CLI, while developers can build their own clients on top of one of the ORAS client libraries.

Use cases

It is not just managing container images that ORAS can do, it can treat OCI registries as a generic artifact store. Some of the most common use cases include:

Artifact Distribution

• Push and pull non-container artifacts (e.g., Helm charts, WASM modules, policy bundles, AI/ML models) using the same infrastructure as container images.
• Simplify artifact versioning, discovery, and retrieval across environments (dev, test, prod) using standard image tags.

Manage ML/AI Models as OCI Artifacts

Package and distribute machine learning models, datasets, or inference pipelines alongside your containers across local filesystem (via OCI layout) and OCI registries.

Supply Chain Security

• Attach security metadata (e.g., SBOMs, signatures, attestations) to container images using oras attach, following the OCI Reference Types.
• Enable secure CI/CD pipelines by distributing and verifying trusted artifacts across OCI-compliant registries.

Backup & Restore of repositories and artifacts

• Air-Gapped Environments: Organizations operating in isolated or high-security environments can use oras backup to export artifacts from a registry to local filesystem, and use oras restore to import them into an internal registry with restricted access.
• Disaster Recovery and Audit Archival: Take periodic snapshots of repositories and store them off-site. In case of accidental deletions, outages, and long-term storage to support regulatory audits, oras restore can be used to quickly recover full registry content.
• Registry Migration: When moving from one container registry provider to another, the pair of commands enables a full repository export, preserving tags, manifests, layers, and referrers.
• Compliance and supply chain security guarantee: Backup and restore the images along with their supply chain artifacts, such as SBOMs, signatures, vulnerability scanning reports.
• Repository Duplication or Promotion: Move artifacts from dev to staging to prod registries reliably using an intermediate backup file.

Multi-platform Image and Artifact Management

Assemble, update, distribute, and annotate multi-architecture images and artifacts across local environments and registries.

How ORAS works

ORAS works similarly to tools you may already be familiar with, such as docker. It allows you to push (upload) and pull (download) things to and from an OCI Registry, and also handles login (authentication) and token flow (authorization). What ORAS does differently is shift the focus from container images to other types of artifacts.

ORAS is the de facto tool for working with OCI Artifacts. It treats media types as a critical piece of the puzzle. Container images are never assumed to be the artifact in question.

By default, when pushing artifacts using ORAS, the config.mediaType field is set to unknown:

application/vnd.unknown.config.v1+json

Authors of new OCI Artifacts are thus encouraged to define their own media types specific to their artifact, which their custom client(s) know how to operate on.

If you wish to start publishing OCI Artifacts right away, take a look at the ORAS CLI. Developers who wish to provide their own user experience should use one of the ORAS client libraries.

ORAS works with any OCI Registries

Here’s the list of OCI Registries that support ORAS:

• CNCF Distribution
• Amazon Elastic Container Registry (ECR)
• Azure Container Registry (ACR)
• Google Artifact Registry
• GitHub Packages Container Registry
• GitLab Container Registry
• JFrog Artifactory
• Docker Hub
• Zot Registry
• Harbor
• Red Hat Quay
• OVHcloud Managed Private Registry (MPR)