Open models with pet

BuiltChecked 16 November 2026

In short

  • The pet command downloads, publishes and holds open models. Every file is checked against its publisher's signature.
  • Built and tested on one machine.
  • No index, relay or witness runs on the internet yet, and every holder is our own. Outside holders are planned.

Not live. No index, relay or witness is running anywhere yet, and no root key has been made. Every command below is tested on one machine (tests/unit/hub-pet.test.ts, npm run hub:drill-pet). Until the founder makes the root key and an index runs, give --index and --root yourself.

pet downloads, publishes and holds open models with no Hugging Face. Every file is checked against its publisher's signature before it is used. Your usual tools keep working: files land in the Hugging Face cache, and pet serve answers on Hugging Face's address for hf download and transformers.

Commands

CommandWhat it does
pet download <owner/name>Gets the model from holders into the Hugging Face cache. Every 1 MiB piece is checked, then the whole file. Prints the exact commit. --revision, --only '*.json,*.safetensors'
pet download <owner/name> --from <folder or address>The same from a copy, with no internet. Files that do not match the signature are refused
pet publish <owner/name> --dir <folder> --license <id>Signs a version straight from a folder and sends it to the indexes. The key is made on first use, readable by you only (~/.config/petrova/hub/publisher.pem), or --signing-key <file>
pet serveHugging Face's address on this machine: HF_ENDPOINT=http://127.0.0.1:4400 hf download <owner/name>
pet hold <owner/name>...Takes models, serves them and tells the indexes. --quota-gb, --keep-free-gb
pet hold --top NPicks the N most downloaded models with the fewest copies (from the signed catalog) and holds them
pet hold ... --relay <address>For a machine behind a home router: others reach it through a relay, and no port is opened
pet copy <owner/name> <folder>Writes a downloaded model with its signatures to a folder (a USB drive)
pet shareServes this machine's downloaded models to machines nearby (--host 0.0.0.0)
pet relayRuns a relay. Every byte passes through it, so it costs its operator bandwidth
pet witness --follow <index>=<key>Watches an index and cosigns what it shows, so a rewritten log is caught
pet catalog crawl / measure / top / verifyThe signed catalog of Hugging Face's public models, most downloaded first

serve, hold, share, relay and witness print one JSON line when ready and run until Ctrl-C.

Whom it trusts

Settings come from flags first, then the environment (PETROVA_HUB_INDEXES, PETROVA_HUB_ROOTS, PETROVA_HUB_TRUST, PETROVA_HUB_WITNESSES, comma-separated), then what is built into the one-file pet.

  • A root key signs numbered lists of publisher and index keys. pet follows the lists one version at a time from the root you gave. An index cannot add a key, and cannot send you back to an older list.
  • An index says what exists and who holds it. It cannot change a file: the publisher's signature names every file's SHA-256 and the hash of its piece list.
  • A holder sends bytes. A holder that signed a different piece list than the publisher is never asked. One that sends a wrong piece is dropped at that piece.
  • A witness keeps the log each index showed it. If an index shows you a log the witness was not shown, the download stops with forked and the evidence is kept in .petrova/forks/. Once a witness holds that proof, it refuses that index key for everyone.

A build made with node scripts/build-cli.mjs --hub-defaults <file> --out <file> has indexes, root keys and witnesses built in, so pet download <owner/name> needs no setup. The repository's own build has none.

For volunteers: paste this into your agent

pet hold --prompt --top 20 --quota-gb 200 prints it:

Set up this machine to hold open AI models for others with Petrova, so they stay available if Hugging Face is down.

  1. Install the pet command if it is missing.
  2. Run: pet hold --top 20 --store ~/.petrova/hold --quota-gb 200
  3. If this machine is behind a home router, add --relay <relay address>.
  4. Keep it running. Report with: pet hold --status --store ~/.petrova/hold

Do not change router settings, and do not use more disk than the quota.

Gated models (those whose publisher asks each user to agree to terms) are never picked. --top picks a model only if the catalog shows a licence that lets anyone pass the files on (Apache-2.0, MIT, BSD, CC0, CC-BY, OpenRAIL and a few more: SHARE_LICENSES in packages/hub/src/volunteer.ts). "Other" and no licence stated are passed over. Models you name yourself (pet hold org/model) are your own choice.

Models already on your machine

If you have used hf download or transformers, your Hugging Face cache (~/.cache/huggingface/hub) already holds models. pet can share them from where they are, with no second copy.

pet have --catalog <catalog> --catalog-key <key>            # what you have, what may be shared, what the network lacks
pet hold --hf-cache --catalog <catalog> --catalog-key <key> --relay <relay address>

Every cached file is hashed before it is shared: large files by SHA-256, small ones by Git's blob hash, as the cache names them. A file is shared only if the signed catalog lists it, by that hash and size, as a file of that model, and the model's licence lets anyone pass it on and it is not gated. Files are served in place and never changed; if a file in the cache changes or is deleted, it is no longer served. They do not count against --quota-gb.

Sharing is your choice: once you hold files, others can see which ones this machine holds.

Limits today

  • No index, relay, witness or catalog copy runs on the internet. The root key does not exist yet.
  • The relay carries every byte. Opening a direct path through home routers (hole punching) is not built.
  • A witness sees which index answers you were shown (their digests, not your files).
  • Offline, an expired key list still counts, because nothing can be asked; the report says so (key_list.expired).
  • An index answer lists at most 32 holders of each file; holders_total says how many there are.
  • --hf-cache shares only models the catalog has read the files of (the top 10,000 today), and only the version the catalog read. A deleted cached file is still announced until the next announcement (every 12 hours); downloaders then drop this holder for that file.
  • The index log keeps every announcement, so it grows with holders (about 1.3 GB a day at 10,000 holders of 150,000 files). Compaction is not built.

Last checked against the code: 16 November 2026. Something wrong? The source of this page is in the repository, so a fix is one edit.