Pulling images

Registry speaks the OCI Distribution pull API, so any OCI-compatible client works: docker pull, podman pull, crane, skopeo, or a Kubernetes node pulling an image for a pod.

Naming an image

An image reference has three parts before the repository:

<registry-host>/<organisation>/<workspace>/<repository>:<tag>

Both the organisation and the workspace may be given as either its name or its UUID, in any combination — all four of these resolve to the same image:

docker pull registry.example.com/acme/production/backend:v1.4.0
docker pull registry.example.com/3f2a…/production/backend:v1.4.0
docker pull registry.example.com/acme/9c81…/backend:v1.4.0
docker pull registry.example.com/3f2a…/9c81…/backend:v1.4.0

A repository name may itself contain slashes — team/service/backend — and the registry resolves the whole remainder as the repository rather than as further parents.

You can address an image by tag or by digest:

docker pull registry.example.com/acme/production/backend:v1.4.0
docker pull registry.example.com/acme/production/backend@sha256:0b1f…

A digest pull is exact: it fetches that artifact and no other, whatever the tags currently point at.

Authenticating

Every request needs a bearer token scoped to the repository you are pulling. Clients handle this for you: on the first request the registry answers 401 with a WWW-Authenticate header naming where to obtain a token and which scope to ask for, and the client fetches one and retries.

The token comes from your own identity: there is no separate registry credential to request or store. See authenticating to the registry for the exchange and for what each token is scoped to.

docker login <registry-host> once per host is normally all you need.

Limits

Limit	Value	Why
Manifest size	4 MiB	A manifest is metadata, not payload. The ceiling bounds what a single request can ask the registry to hold in memory; a manifest above it is refused rather than truncated.

Layer blobs have no size limit imposed by the registry. They are streamed in bounded chunks, so pulling a large image does not require the registry to hold it in memory, and many clients can pull large images at once without exhausting it.

Range requests are supported on blobs, so an interrupted pull resumes rather than restarting.

When a pull fails

Errors come back in the standard OCI envelope, and your client will usually surface the code:

What you see	What it means
`UNAUTHORIZED`	No credential, or one the registry could not verify. Run `docker login`.
`DENIED`	Your token is valid and names this repository, but does not permit pulling from it — or the workspace has been archived, in which case the message says so.
`NAME_UNKNOWN`	The repository does not exist, or your credential does not grant you access to it. These are deliberately indistinguishable — see below.
`MANIFEST_UNKNOWN`	No manifest under that tag or digest that this client can be served. Also returned when your `Accept` header admits none of the manifest’s available media types.
`BLOB_UNKNOWN`	The repository holds no such blob. A blob belonging to a different repository is not reachable by digest alone.
`DIGEST_INVALID`	The digest in the reference is not well formed.
`UNSUPPORTED`	The operation is part of the Distribution specification but not currently served — pushing, tag listing, and the catalogue.

Why “not found” and “not yours” look identical

NAME_UNKNOWN deliberately covers both “this repository does not exist” and “it exists and you have no access to it”.

If those answered differently, anyone holding a token for any repository could discover which repository names exist across the whole platform simply by probing them and comparing the responses. Collapsing the two means a probe tells you nothing you did not already know.

The consequence to be aware of: a typo in a repository name and a genuine permission problem produce the same error. If you are confident the name is right, check your access before concluding the image is missing.

DENIED is different, and the distinction is deliberate. It is returned only when your token already names the repository — so its holder knows the repository exists, and telling them why they were refused discloses nothing new.

Suspended and archived workspaces

Workspace state	Pull
Active	works
Suspended	works — suspension freezes changes, not reads, so running workloads keep pulling
Archived	refused with `DENIED`, naming the archived state

Suspension is deliberately readable. A suspended workspace often has workloads still running, and those workloads restart, reschedule, and scale; refusing their pulls would turn a billing or administrative hold into an outage.