By Parnell Springmeyer
Member of Technical Staff

hocker is a suite of utilities that:

  • fetch the registry manifest for a docker image
  • fetch the configuration of a docker image
  • fetch any layer of a docker image
  • fetch and assemble a whole docker image
  • generate Nix build instructions from a registry manifest for a docker image (we won’t cover this utility in this post)

hocker utilities support two modes of authentication with privately hosted docker registries and “transparent” public-token authentication for the public docker hub registry.

hocker does not replace docker; however, it does decouple fetching docker images from running docker containers.

Why did you build this?

There are two motivating reasons:

  • we want to assemble a docker image from our registry without requiring the docker daemon
  • we want to fetch individual layers of a docker image from our registry for a granular — and efficient — deployment of a docker image to environments where we cannot use docker pull

Integrating docker containers into a NixOS system (without using docker pull) stimulated these two requirements. Note that Nix and NixOS are not required to use these utilities.

Fetch a docker image without using docker pull

Let’s dive right in and fetch the hello-world docker image from (note that the repository name for official images on the public docker hub is “library”):

$ hocker-image \
--out ./hello-world.tar.gz \
library/hello-world linux
Downloading layer: ca4f61b => decompressed => wrote f999ae2

The result is a complete docker image:

$ tar --list --file ./hello-world.tar.gz

… which we load into docker using docker load:

$ docker load < hello-world.tar.gz
Loaded image:

… and then run:

$ docker run --rm \
Hello from Docker!
This message shows that your installation appears to be working correctly.

Fetch the registry manifest and a layer, of a docker image

If we want to fetch the individual layers of a docker image then we need to retrieve the manifest of binary blobs on the registry for the image; we can do this using hocker-manifest:

$ hocker-manifest library/hello-world linux | jq
"schemaVersion": 2,
"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
"config": {
"mediaType": "application/vnd.docker.container.image.v1+json",
"size": 1510,
"digest": "sha256:f2a91732366c0332ccd7afd2a5c4ff2b9af81f549370f7a19acd460f87686bc7"
"layers": [
"mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
"size": 985,
"digest": "sha256:ca4f61b1923c10e9eb81228bd46bee1dfba02b9c7dac1844527a734752688ede"

… the manifest says there is one layer we can fetch; the layer is keyed by its digest with the sha256: part stripped off:

$ hocker-layer \
--out ./hello-world-layer-ca4f61b.tar.gz \
--layer ca4f61b1923c10e9eb81228bd46bee1dfba02b9c7dac1844527a734752688ede \
library/hello-world linux
Downloading layer: ca4f61b => wrote ca4f61b

… the layer contains a hello program:

$ tar --list --file ./hello-world-layer-ca4f61b.tar.gz

… which is also the CMD entrypoint of the container as indicated by the image’s configuration JSON:

$ hocker-config library/hello-world linux | jq
"config": {
"Cmd": [


We’ve pulled a docker image from a registry without using the docker client or going through the docker daemon. We also fetched three other artifacts of the hello-world docker image that the stock docker tooling elides from you:

  • the registry’s manifest of the artifacts that compose the image
  • an individual layer of the image; and,
  • the image configuration — as JSON

In a follow-on blogpost, I will show how we use the hocker utilities with Nix and NixOS.

You can find hocker on GitHub and Hackage.


Thanks to Gabriel Gonzalez (@GabrielG439) for reading drafts and providing feedback.

Awake Security
Computer Science Problems