Skip to main content
Registry • 2 mins read

Pushing models & images

Pushing models & images

Pushing always requires a namespace. The hippius-hub CLI provisions one — and the docker credentials you'll need — in a single command.

Namespaces​

Every artifact lives at <namespace>/<repo>:<tag>. New namespaces are public by default — anyone can pull, only you can push. Pricing tiers gate storage quota; see hippius.com/hippius-hub for the plans.

Provision a namespace​

Run these three commands in order — the first time only:

hippius-hub registry plans                       # see pricing tiers
hippius-hub registry check my-models             # is the name free?
hippius-hub registry provision my-models --docker-login

provision --docker-login does three things in one shot: creates your namespace, mints docker credentials, and runs docker login registry.hippius.com for you. The hippius-hub CLI's own upload / download commands also start working immediately because the credentials are cached at ~/.cache/hippius/hub/token.

Save the robot secret

The robot secret prints once at the bottom of registry provision. If you lose it, rotate with hippius-hub registry rotate-token — it issues a new secret and updates the local cache.

Push​

from hippius_hub import upload_folder

upload_folder(
    folder_path="./outputs/checkpoint-1000",
    repo_id="my-models/qwen-7b",
    revision="v1",
    allow_patterns=["*.safetensors", "*.json"],
    delete_patterns="*.tmp",     # prune any *.tmp from the existing revision
    commit_message="Initial checkpoint",
)

Drop-in for upload_folder. Re-running it merges into the existing manifest at that revision — individual files get added or replaced without wiping the rest.

For a single file, use upload_file(path_or_fileobj, path_in_repo, repo_id, revision).

Mirror a HuggingFace model​

The fastest way to put an existing HF model behind your own namespace — pull with hf, push with hippius-hub:

# 1. Grab the model from HF
pip install -U "huggingface_hub[cli]" hf_transfer
HF_HUB_ENABLE_HF_TRANSFER=1 hf download Qwen/Qwen2.5-7B-Instruct --local-dir ./qwen-7b

# 2. Push the whole folder under your namespace as :v1
hippius-hub upload my-models/qwen-7b ./qwen-7b --revision v1

# 3. Confirm it landed and got indexed
hippius-hub registry repos
hippius-hub models show my-models/qwen-7b v1

The hf download CLI handles the HF side; hippius-hub upload chunks and parallelizes the push to your namespace.

Public vs private​

hippius-hub registry publicity public      # anyone can pull
hippius-hub registry publicity private     # only your credentials can pull

Toggling publicity also resizes your quota to the plan's public or private tier.

Rotate credentials​

hippius-hub registry rotate-token --docker-login

Issues a new docker secret and writes it to the local cache. The old secret stops working immediately — relevant for CI/CD pipelines that hold a copy of the secret. Re-distribute before rotating.

Troubleshooting docker push 500​

If docker push loops with 500 Cannot find server., check docker info | grep -i proxy. A daemon-level proxy (e.g. http.docker.internal:3128) in Docker Desktop routes the push through an unreachable proxy and the registry is never hit.

Fix: Docker Desktop → Settings → Resources → Proxies → disable it or bypass registry.hippius.com, then restart Docker Desktop. NO_PROXY in your shell does not help — the daemon ignores it.

Hugging Face features not supported

Inference Endpoints, Spaces, Webhooks, Collections, and Discussions raise NotImplementedError — they have no OCI equivalent. Everything required for from_pretrained works.

Where to next​

  • Pull — download from Python, CLI, or docker pull.
  • CLI reference — every hippius-hub command, grouped by goal.