Workflow:Ollama Ollama Model Registry Operations
| Knowledge Sources | |
|---|---|
| Domains | LLMs, Model_Management, Registry |
| Last Updated | 2026-02-14 22:00 GMT |
Overview
End-to-end process for pushing locally created models to the Ollama registry and pulling models from the registry, including manifest management, blob transfer, and authentication.
Description
This workflow covers the complete model distribution lifecycle using the Ollama model registry. Models are stored as content-addressable blobs organized by manifests, following a Docker/OCI-inspired design. The push operation uploads model layers (weights, tokenizer, configuration) as blobs to the registry and publishes a manifest. The pull operation downloads a manifest and its referenced blobs with parallel transfers, resume support, and integrity verification. Both operations use HTTP-based authentication with SSH key signing.
Usage
Execute the push workflow when you have created a custom model locally (via Modelfile or conversion) and want to share it through the Ollama registry for others to use. Execute the pull workflow when you want to download a model from the registry for local use, either from the public Ollama library or a private namespace.
Execution Steps
Step 1: Authentication
Authenticate with the Ollama registry using SSH-based token signing. When the registry returns an HTTP 401 challenge with a nonce, the client signs the nonce using the user's SSH private key and returns the signature as a Bearer token. This establishes the user's identity for push authorization and private model access.
Key considerations:
- Authentication uses Ed25519 SSH keys stored in the user's ~/.ollama directory
- The challenge-response flow follows a custom protocol (not OAuth)
- Pull operations for public models do not require authentication
- Push operations always require authentication to verify namespace ownership
Step 2: Manifest Resolution
For pull operations, request the model manifest from the registry by name and tag. The manifest is a JSON document listing all blob layers that compose the model, each identified by a SHA-256 digest, media type, and size. For push operations, read the local manifest and prepare the list of blobs to upload.
Key considerations:
- Model names follow the format namespace/model:tag
- Manifests reference blobs by content digest, enabling deduplication across models
- The manifest includes layer types: model weights, tokenizer, template, system prompt, parameters, license
- A model may share weight blobs with other models derived from the same base
Step 3: Blob Transfer (Download or Upload)
For pull: Download each blob layer that is not already present in the local store. Downloads use parallel chunked transfers for large files (model weights), with support for HTTP range requests enabling resume from interrupted downloads. Each downloaded blob is verified against its expected SHA-256 digest.
For push: Upload each blob that the registry does not already have. The upload checks for blob existence first (HEAD request), supports cross-repository mounting for shared blobs, and uses chunked uploads with progress tracking for large files.
Key considerations:
- Blob transfers are idempotent; re-running after a failure resumes where it left off
- Download chunks are fetched in parallel to maximize throughput
- Upload uses chunked transfer with a session URL for reliability
- Shared base model blobs may already exist in the registry (cross-repository mount)
Step 4: Local Manifest Management
For pull: Write the downloaded manifest and blob references to the local content-addressable store. The manifest is stored under the model's name and tag, making it available for subsequent load and run operations.
For push: After all blobs are uploaded, push the manifest to the registry, making the model available for others to pull.
Key considerations:
- Local manifests are stored in the OLLAMA_MODELS directory (default: ~/.ollama/models)
- Blobs are stored by their SHA-256 digest, enabling deduplication
- Old manifest versions are replaced when pulling a newer version of a tag
- The blob store supports migration from legacy naming formats
Step 5: Integrity Verification
After pull completion, verify the integrity of all downloaded blobs by recomputing their SHA-256 digests and comparing against the manifest. For push, the registry performs server-side verification of uploaded blob digests. Any digest mismatch triggers a re-download or re-upload of the affected blob.
Key considerations:
- Verification is automatic and cannot be disabled
- Corrupted blobs are re-downloaded automatically
- The verification step ensures the local model is identical to the registry version
- Sparse file support on Windows optimizes disk allocation for partially downloaded blobs