HologramHologram

Concepts

Verification

The one rule that makes a download from anywhere safe, and the three ways to apply it.

Markdown

A file you downloaded is only as trustworthy as the host that served it, unless you already knew what its bytes should hash to. The hub gives you that number before you fetch anything.

The rule

Hash what arrives. Keep the file only if its hash equals the value the tree gave you: the SHA-256 in lfs.oid for a large file, the git blob SHA-1 in oid for a small one. The expected hash comes from the tree and never from the source that served the bytes.

The hub does not verify on read. It cannot: the bytes never pass through it. Verification happens on your machine, or inside a client that does it for you.

Where the expected hash comes from

Dialect Field Source of truth
Hugging Face Hub API lfs.oid (SHA-256, large files) and oid (git blob SHA-1, every file) in /api/models/<owner>/<name>/tree/main the tree, exactly as Hugging Face publishes it
SHA256SUMS under /via/<source>/ one line per file, in sha256sum format generated by the hub from the index; never redirected
OCI each layer's digest in the manifest the index; a layer is one raw file, so its digest is the file's SHA-256
Ollama the layer digests Ollama checks itself the index
Objects files[].sha256 in the model object the object, whose own address is the BLAKE3 of its bytes

The Etag on a /resolve/ redirect is the same hash the tree names, quoted. It is a convenience, not a second source.

Check one file

curl -sL https://gethologram.ai/hexgrad/Kokoro-82M/resolve/main/EVAL.md -o EVAL.md
git hash-object --no-filters EVAL.md
484ac8dcd971465258007528fb8bc4a99cf98633

That equals oid for EVAL.md in the tree. Git's blob SHA-1 is SHA-1 over blob <size>, a zero byte, then the bytes, so any SHA-1 tool can compute it. For a large file, sha256sum the bytes and compare with lfs.oid.

Check a whole download

After hf download, with Hugging Face's own tool:

hf cache verify hexgrad/Kokoro-82M

It hashes every cached file against the tree, large files by SHA-256 and small ones by git blob SHA-1, and exits non-zero on any mismatch, so it works as a gate in a script. Files you did not download are reported as missing, not failed; add --fail-on-missing-files to make them fail too.

Clients that check for you

Client What it checks What you do
Ollama the SHA-256 of every layer, before the model is usable nothing
oras, modctl, skopeo, crane, containerd every blob against its digest nothing
huggingface_hub the size it was told to expect; not the hash hf cache verify <owner>/<name>
curl nothing sha256sum or git hash-object --no-filters, compared with the tree

On a mismatch

Drop the file and fetch it again from another source: put /via/ipfs or /via/modelscope in front of the path. The expected hash does not change; only the source does. If every source disagrees with the index, the index is wrong for that file, and the hub wants to know: use POST /api/account/request from a signed-in account, or open an issue on the repository.

Check an object

Objects are addressed by BLAKE3, not SHA-256. The address you asked for must equal the BLAKE3 of the bytes you received. With the blake3 Python package:

curl -s https://gethologram.ai/api/v1/objects/blake3:3cc11e52049117dfc397240fddc7a4d3aa392ded7f623986e4e5757371363d9e -o model.json
python3 -c "from blake3 import blake3; print(blake3(open('model.json','rb').read()).hexdigest())"
3cc11e52049117dfc397240fddc7a4d3aa392ded7f623986e4e5757371363d9e

The Objects page explains what that object is.