How to Use Existing OCI Images with Apple’s Container Tool

Yes, Apple’s container tool is built OCI‑first and consumes standard OCI images from Docker Hub, private registries, or local storage without requiring conversion.

The apple/container repository provides a lightweight container runtime for macOS that is fully compliant with the Open Container Initiative (OCI) specifications. Because the tool is implemented in Swift via the underlying Containerization package, it natively supports the OCI Image Specification and can pull, run, build, and push images that work with Docker, Buildah, or any other OCI-aware runtime.

OCI-First Architecture

According to the README, the tool both consumes and produces OCI‑compatible images. As documented in docs/technical-overview.md, the CLI communicates with the Containerization Swift package to handle image manifests, layers, and configurations exactly as defined by the OCI Image Spec. This means any existing image that conforms to the specification—regardless of whether it was built with Docker, Podman, or BuildKit—can be used unchanged.

Supported OCI Workflows

The container CLI provides explicit commands for interacting with OCI images across the full container lifecycle.

Pulling Images from Registries

The container pull command fetches image manifests, layers, and configuration files from any OCI‑compliant registry. This operation validates registry hostnames according to the OCI Distribution specification, as implemented in Sources/ContainerResource/Registry/RegistryResource.swift.

container pull docker.io/library/alpine:latest

Running OCI Images

When you execute container run, the tool starts a lightweight VM, loads the OCI image layers, and executes the entrypoint defined in the image’s OCI configuration. This behavior is documented in the Technical Overview and confirmed by the VM orchestration logic in the source.

container run docker.io/library/alpine:latest \
    --env PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin \
    --exec /bin/sh -c "echo Hello from Alpine inside a macOS VM!"

Building OCI-Compatible Images

The container build command uses BuildKit under the hood to produce OCI‑compatible images. As noted in docs/command-reference.md, the output is written directly to the local content store in OCI format.

container build -t myorg/ubuntu-with-curl:latest .

Saving and Exporting

You can export any local image to a tarball that follows the OCI Image Layout specification. The implementation in Sources/ContainerCommands/Image/ImageSave.swift explicitly creates "an OCI compatible tar archive" containing the manifest, configuration, and layer blobs.

container image save myorg/ubuntu-with-curl:latest -o ubuntu-curl.tar

Pushing to Registries

The container push command uploads image manifests and layers using the OCI Distribution spec. The registry interaction logic in Sources/ContainerResource/Registry/RegistryResource.swift validates hostnames and ensures compliance with OCI standards, while Sources/ContainerCommands/Registry/RegistryLogin.swift handles authentication via the macOS Keychain.

container push myorg/ubuntu-with-curl:latest myregistry.example.com/myorg/ubuntu-with-curl:latest

Complete Usage Examples

Below is a complete workflow demonstrating how to use existing OCI images without modification.

1. Pull an existing image from Docker Hub:

container pull docker.io/library/alpine:latest

2. Run the image interactively:

container run docker.io/library/alpine:latest \
    --env PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin \
    --exec /bin/sh -c "echo Hello from Alpine inside a macOS VM!"

3. Build a new OCI image from a Dockerfile:

cat > Dockerfile <<'EOF'
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y curl
CMD ["bash"]
EOF

container build -t myorg/ubuntu-with-curl:latest .

4. Save the image to an OCI Layout tarball:

container image save myorg/ubuntu-with-curl:latest -o ubuntu-curl.tar

5. Push to a private registry:

container push myorg/ubuntu-with-curl:latest myregistry.example.com/myorg/ubuntu-with-curl:latest

Note: Ensure the container system service is running (container system start) before executing these commands.

Key Implementation Files

The following source files confirm the tool’s OCI compatibility:

• README.md — Declares that container works with OCI‑compatible images.
• docs/technical-overview.md — Describes the OCI‑first design and interoperability guarantees.
• docs/command-reference.md — Documents CLI flags for building, pulling, and running OCI images.
• Sources/ContainerCommands/Image/ImageSave.swift — Implements saving images as OCI‑compatible tar archives.
• Sources/ContainerResource/Registry/RegistryResource.swift — Handles OCI registry hostname validation and distribution spec compliance.
• Sources/ContainerCommands/Registry/RegistryLogin.swift — Manages OCI registry authentication with Keychain integration.

Summary

• Apple’s container tool is OCI‑first, meaning it natively consumes and produces standard OCI images.
• You can pull, run, build, save, and push images without conversion or modification.
• The tool validates registry compliance against the OCI Distribution specification.
• All image exports follow the OCI Image Layout spec, ensuring portability with other runtimes.

Frequently Asked Questions

Can I run Docker Hub images without conversion?

Yes. Images from Docker Hub, GHCR, or any OCI‑compliant registry work immediately. The container pull command downloads the manifest and layers exactly as Docker or Podman would, and container run executes the OCI config’s entrypoint without transformation.

Does Apple’s container tool support OCI Image Layout exports?

Yes. The container image save command creates tar archives that strictly follow the OCI Image Layout specification. This is explicitly implemented in Sources/ContainerCommands/Image/ImageSave.swift, which preserves the manifest, configuration, and layer blobs in the standard directory structure.

What registry authentication methods are supported?

The tool supports standard OCI registry authentication via the container login command, which stores credentials in the macOS Keychain. The implementation in Sources/ContainerCommands/Registry/RegistryLogin.swift and Sources/ContainerResource/Registry/RegistryResource.swift handles token exchange and hostname validation according to the OCI Distribution spec.

Is there any image format that isn’t supported?

The tool requires strict OCI Image Specification compliance. Legacy Docker schema v1 images or non‑OCI formats (such as proprietary VM disk images) are not supported. If an image works with Docker or Podman today, it is OCI‑compliant and will work with Apple’s container tool.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}