Images from your registry

Hangar can run a public container image straight from Docker Hub, GitHub Container Registry, NVIDIA NGC, Amazon ECR Public or Quay, so you do not need Docker on your machine. You pay for the jobs of the image.

Give the image as REGISTRY/NAME@sha256:DIGEST. Hangar fetches the image into Sydney once, checks every byte against the digest, and stores the image under your organisation's key. Hangar then checks the image as Hangar checks a pushed image. The worker takes the image from Sydney only.

$ hangar upload --image docker.io/library/python@sha256:5c0e9a17d2b4a1f0c3e5d7b9a2c4e6f8a0b1c3d5e7f9a2b4c6d8e0f1a3b5c7d9
Ctrl C stops this wait. The fetch continues in Sydney, and the same command follows it again.
Fetching docker.io/library/python@sha256:5c0e9a17d2b4 into Sydney: 3 of 7 layers, 0.4 of 1.1 GB.
Fetched docker.io/library/python@sha256:5c0e9a17d2b4 into Sydney: 7 layers, 1.1 GB.
Registered a one-time pull of docker.io/library/python@sha256:5c0e9a17d2b4a1f0c3e5d7b9a2c4e6f8a0b1c3d5e7f9a2b4c6d8e0f1a3b5c7d9.
Preflight passed: linux/amd64 (GPU pools), linux/arm64 (CPU sandbox), entrypoint python3.

The registries

Hangar fetches public images from these registries:

Registry	A reference starts with
Docker Hub	`docker.io/` (a name with no registry, such as `python@sha256:...`, is Docker Hub's `library/python`)
GitHub Container Registry	`ghcr.io/`
NVIDIA NGC	`nvcr.io/`
Amazon ECR Public	`public.ecr.aws/`
Quay	`quay.io/`

To use an image from another registry, or a private image, push the image from an OCI archive with hangar upload --image ARCHIVE --name NAME:TAG (Bring your image).

By digest

Hangar fetches by digest, because a tag can point to other bytes tomorrow. A digest means that what runs is what you approved. Hangar reads a tag beside the digest (python:3.12@sha256:...) and sets the tag aside. Hangar refuses a reference with a tag and no digest, with image_pull_digest_required. The digest is on the image's tag page on the registry, and crane digest REFERENCE prints the digest on any computer.

What Hangar fetches

The manifest that you name. For a multi-platform index, Hangar fetches the linux/amd64 image, which the GPU pools run, and the linux/arm64 image, which the CPU sandbox runs. Hangar fetches no other platform.
Each image's config, then the image's layers.
Before Hangar keeps a part, Hangar checks every manifest, config and layer against the SHA-256 digest that names the part. Hangar also checks each layer against the layer's declared size. Hangar does not keep a part that does not match, and the image fails with image_fetch_digest_mismatch.
Hangar does not fetch a layer again when your organisation already holds the layer, from a push or an earlier fetch. Hangar stores such a layer once.

Each kept part is an object of your organisation, with a received movement record, as a pushed layer is.

Limits

Each pool allows an image up to a set size: 200 GB on a GPU booking and 8 GiB in the CPU sandbox. Hangar reads the sizes that the manifest declares and stops a larger image before Hangar fetches any layer. The image fails with preflight_too_large, as a pushed image does.
Your organisation fetches one image at a time. A second fetch waits, and the fetch line says so.
Each organisation fetches up to 300 GB of layers an hour. A layer that would pass the limit waits until the next hour starts.
When a registry does not answer, Hangar tries again, with a longer wait each time, up to five attempts. Each attempt keeps the layers that Hangar already fetched. After the fifth attempt, the image fails with image_fetch_unreachable.

Following a fetch

POST /v1/images/pull answers at once. The image is pending, status is fetching, and fetch shows the progress. GET /v1/images shows the same fetch on the image:

state is queued, fetching, stored or failed.
waiting is another_fetch, hourly_allowance or retry.
bytes_fetched shows progress towards bytes_total, and layers_done shows progress towards layers_total.

When the bytes are in Sydney, the image changes to passed or failed. The reason is in preflight_error, in three parts. Hangar answers a job of an image that is still fetching with image_preflight_pending.

Ctrl C ends the CLI's wait, and the fetch continues. Run the same command again to follow the fetch. When Sydney already stores the digest, Hangar checks the image at once.

When a fetch fails

Code	What it means
`image_fetch_not_found`	The registry has no public image with that digest.
`image_fetch_unreachable`	The registry did not answer after five attempts.
`image_fetch_digest_mismatch`	The registry sent a part that does not match its digest.
`image_fetch_redirect_refused`	The registry sent Hangar to a download address outside the registry's list.
`image_registry_not_allowed`	The reference points to a registry that is not in the table above.

Each answer shows the next step and a second step. If you register the same reference again, Hangar starts a new fetch and keeps every layer that the last fetch fetched.

Read this page as Markdown