Boxr’s registry pull path accepts schema-2 OCI image manifests and Docker distribution manifests, including multi-platform indexes and manifest lists.
boxr image pull --platform linux/amd64 ghcr.io/example/service:v1
boxr image pull --platform linux/arm64 ghcr.io/example/service:v1
boxr image inspect ghcr.io/example/service:v1
boxr image verify ghcr.io/example/service:v1
The puller accepts these layer media types:
application/vnd.oci.image.layer.v1.tarapplication/vnd.oci.image.layer.v1.tar+gzipapplication/vnd.oci.image.layer.v1.tar+zstdapplication/vnd.docker.image.rootfs.diff.tarapplication/vnd.docker.image.rootfs.diff.tar.gzipapplication/vnd.boxr.rootfs.v1.tar+gzipOCI Zstandard-compressed layers (application/vnd.oci.image.layer.v1.tar+zstd) are supported alongside uncompressed and gzip layers. Foreign/non-distributable layer URLs are not currently supported. Unsupported media types fail before the layer is downloaded; Boxr never guesses the compression format from a filename.
Independent image layers are downloaded and integrity-checked with a bounded pool of up to four workers. This reduces pull latency for multi-layer images without creating one goroutine or network request per layer. Results are retained by manifest index, so filesystem application remains strictly ordered. A failed download or digest check cancels outstanding requests and removes all temporary layer files created by the pull.
Concurrent requests share a synchronized Bearer-token cache. A group of requests that receives an authentication challenge performs a single token refresh instead of racing to issue duplicate token requests.
Before a pull is returned, Boxr validates manifest and config descriptors, selects the requested Linux platform, and checks that the config has one valid rootfs.diff_ids entry per manifest layer. Each layer download is checked against its descriptor SHA-256 digest and declared size. The uncompressed tar stream is then hashed and compared with the matching config diff ID.
Verified layers are applied in manifest order. The extractor supports OCI/Docker whiteouts and opaque-directory markers, regular files, directories, safe symlinks and safe hard links. It rejects path traversal, escaping relative symlinks, duplicate/conflicting entries, special device entries, oversized archives and invalid hard links. The resulting filesystem is imported through Boxr’s local content-addressed image store; registry layer boundaries are not preserved locally.
These limits bound metadata and layer downloads; they are not a substitute for adequate disk-space planning.
Registry pushes publish an OCI image manifest with the standard application/vnd.oci.image.layer.v1.tar+gzip layer media type. Boxr’s private local layer media type is translated at publication time; the compressed layer bytes and SHA-256 digest remain unchanged. OCI consumers and Docker-compatible registry clients therefore do not need to understand Boxr’s private media type.
The local image store currently flattens imported Docker/OCI layers into one canonical Boxr rootfs layer. Push therefore publishes one OCI layer and does not preserve arbitrary multi-layer history, build cache metadata, or original layer boundaries.