Hanzo
Services

Hanzo Registry

OCI-compliant container and model artifact registry with vulnerability scanning, image signing, multi-arch builds, and pull-through caching.

Hanzo Registry

Hanzo Registry is a unified container and model artifact registry for the Hanzo platform. It stores OCI-compliant Docker images, model weights, and versioned artifacts with built-in vulnerability scanning, image signing, garbage collection, and multi-architecture support.

Registry: registry.hanzo.ai Gateway: api.hanzo.ai/v1/registry/* Console: console.hanzo.ai/registry Mirror: ghcr.io/hanzoai/*

Features

  • OCI-Compliant: Full compliance with the OCI Distribution Spec -- works with Docker, Podman, Buildah, and any OCI client
  • Model Artifact Registry: Store and version model weights, checkpoints, LoRA adapters, and GGUF quantizations alongside containers
  • Multi-Architecture: Native support for linux/amd64 and linux/arm64 manifests with automatic manifest list resolution
  • Vulnerability Scanning: Automated CVE scanning on every push with configurable severity gates
  • Image Signing: Cosign and Notary v2 signatures for supply chain integrity verification
  • Immutable Digests: Content-addressable SHA-256 digests guarantee reproducible deployments
  • Pull-Through Cache: Transparent caching proxy for Docker Hub, GHCR, and upstream registries
  • Garbage Collection: Automated cleanup of untagged manifests and unreferenced blobs
  • Version Tagging: Semantic version tags, Git SHA tags, and mutable channel tags (latest, stable, canary)
  • CI/CD Integration: Native support for GitHub Actions, GitLab CI, and Hanzo Platform pipelines
  • RBAC: Fine-grained access control per namespace and repository via Hanzo IAM
  • Replication: Cross-region replication for low-latency pulls from any edge location

Architecture

┌──────────────────────────────────────────────────────────────────────┐
│  Clients                                                             │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌────────────────┐   │
│  │ docker    │  │ podman    │  │ buildah   │  │ hanzo CLI      │   │
│  │ push/pull │  │ push/pull │  │ push/pull │  │ registry push  │   │
│  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘  └──────┬─────────┘   │
│        │               │               │               │             │
└────────┼───────────────┼───────────────┼───────────────┼─────────────┘
         │               │               │               │
         ▼               ▼               ▼               ▼
┌──────────────────────────────────────────────────────────────────────┐
│  registry.hanzo.ai                                                    │
│  ┌────────────────────────────────────────────────────────────────┐  │
│  │  Hanzo Registry                                                │  │
│  │  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │  │
│  │  │ OCI Dist   │ │ Auth /     │ │ Vuln       │ │ Signing    │ │  │
│  │  │ API v2     │ │ RBAC       │ │ Scanner    │ │ (Cosign)   │ │  │
│  │  └────────────┘ └────────────┘ └────────────┘ └────────────┘ │  │
│  │  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │  │
│  │  │ Manifest   │ │ Pull-Thru  │ │ Garbage    │ │ Replication│ │  │
│  │  │ Lists      │ │ Cache      │ │ Collection │ │ Controller │ │  │
│  │  └────────────┘ └────────────┘ └────────────┘ └────────────┘ │  │
│  └────────────────────────────────────────────────────────────────┘  │
│                              │                                        │
│                    ┌─────────┴──────────┐                            │
│                    │  Hanzo S3 Backend   │                            │
│                    │  (s3.hanzo.ai)      │                            │
│                    └────────────────────┘                            │
└──────────────────────────────────────────────────────────────────────┘

Blob storage is backed by Hanzo S3 (s3.hanzo.ai), giving the registry the same durability, encryption, and lifecycle management as all other Hanzo storage services.

Quick Start

Authenticate

# Login with your Hanzo credentials
docker login registry.hanzo.ai
# Username: your-hanzo-email
# Password: your-api-key (or `hanzo auth token`)

# Or use a Hanzo API key directly
echo "$HANZO_API_KEY" | docker login registry.hanzo.ai -u hanzo --password-stdin

Push a Container Image

# Tag your local image for Hanzo Registry
docker tag my-app:latest registry.hanzo.ai/my-org/my-app:v1.0.0

# Push
docker push registry.hanzo.ai/my-org/my-app:v1.0.0

# Push with multiple tags
docker tag my-app:latest registry.hanzo.ai/my-org/my-app:latest
docker push registry.hanzo.ai/my-org/my-app:latest

Pull a Container Image

# Pull by tag
docker pull registry.hanzo.ai/my-org/my-app:v1.0.0

# Pull by immutable digest (recommended for production)
docker pull registry.hanzo.ai/my-org/my-app@sha256:abc123...

# Pull a Hanzo platform image
docker pull registry.hanzo.ai/hanzoai/llm-gateway:latest

Multi-Architecture Build and Push

# Create a multi-arch builder
docker buildx create --name hanzo-builder --use

# Build and push for both amd64 and arm64
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag registry.hanzo.ai/my-org/my-app:v1.0.0 \
  --push .

Image Management

Tagging Strategy

Hanzo Registry supports three tagging patterns:

PatternExampleUse Case
Semantic versionv1.2.3Release artifacts
Git SHAsha-a1b2c3dTraceability to exact commit
Channellatest, stable, canaryMutable pointers for deployment tracks

Semantic version tags and Git SHA tags are treated as immutable by default. Pushing to an existing immutable tag returns an error unless you explicitly overwrite with --force.

Listing Repositories and Tags

# List all repositories in your namespace
curl -s -H "Authorization: Bearer $HANZO_API_KEY" \
  https://registry.hanzo.ai/v2/_catalog | jq .

# List tags for a repository
curl -s -H "Authorization: Bearer $HANZO_API_KEY" \
  https://registry.hanzo.ai/v2/my-org/my-app/tags/list | jq .

Deleting Images

# Delete a specific tag
curl -X DELETE -H "Authorization: Bearer $HANZO_API_KEY" \
  https://registry.hanzo.ai/v2/my-org/my-app/manifests/sha256:abc123...

# Garbage collection runs automatically after deletion
# Unreferenced blobs are cleaned up within 24 hours

Immutable Digests

Every image pushed to the registry receives a content-addressable SHA-256 digest. Use digests in production deployments to guarantee bit-for-bit reproducibility:

# Kubernetes deployment (recommended)
containers:
  - name: my-app
    image: registry.hanzo.ai/my-org/my-app@sha256:abc123def456...

Model Registry

Hanzo Registry extends OCI distribution to store ML model artifacts alongside container images. Model artifacts are stored as OCI artifacts with custom media types.

Push a Model

# Using ORAS (OCI Registry as Storage)
oras push registry.hanzo.ai/my-org/models/llama-3-8b:v1 \
  --artifact-type application/vnd.hanzo.model.v1 \
  ./model.safetensors:application/vnd.hanzo.safetensors \
  ./config.json:application/json \
  ./tokenizer.json:application/json

# Push a GGUF quantization
oras push registry.hanzo.ai/my-org/models/llama-3-8b:q4_k_m \
  --artifact-type application/vnd.hanzo.model.v1 \
  ./llama-3-8b-q4_k_m.gguf:application/vnd.hanzo.gguf

Pull a Model

# Pull all artifacts for a model version
oras pull registry.hanzo.ai/my-org/models/llama-3-8b:v1 -o ./model-dir/

# Pull a specific layer by digest
oras pull registry.hanzo.ai/my-org/models/llama-3-8b@sha256:abc123...

Supported Model Formats

FormatMedia TypeExtension
SafeTensorsapplication/vnd.hanzo.safetensors.safetensors
GGUFapplication/vnd.hanzo.gguf.gguf
PyTorchapplication/vnd.hanzo.pytorch.pt, .pth
ONNXapplication/vnd.hanzo.onnx.onnx
LoRA Adapterapplication/vnd.hanzo.lora.safetensors
Tokenizerapplication/json.json
Model Configapplication/json.json

Model Versioning

Models follow the same tagging strategy as container images. Use semantic versions for releases and descriptive tags for variants:

registry.hanzo.ai/my-org/models/llama-3-8b:v1.0.0          # Full precision
registry.hanzo.ai/my-org/models/llama-3-8b:v1.0.0-q4_k_m   # Quantized
registry.hanzo.ai/my-org/models/llama-3-8b:v1.0.0-lora-sft  # Fine-tuned adapter

Security

Vulnerability Scanning

Every image pushed to Hanzo Registry is automatically scanned for known CVEs. Scan results are available in the console and via API.

# View scan results for an image
curl -s -H "Authorization: Bearer $HANZO_API_KEY" \
  https://api.hanzo.ai/v1/registry/my-org/my-app/v1.0.0/vulnerabilities | jq .

Configure severity gates to block deployments with critical vulnerabilities:

# .hanzo/registry.yaml
scan:
  enabled: true
  severity_gate: high    # Block pulls if HIGH or CRITICAL CVEs found
  ignore:
    - CVE-2024-0000      # Known false positive

Image Signing

Sign images with Cosign to establish a verified supply chain:

# Generate a key pair (or use KMS-backed keys)
cosign generate-key-pair

# Sign an image after push
cosign sign --key cosign.key registry.hanzo.ai/my-org/my-app:v1.0.0

# Sign with Hanzo KMS (recommended)
cosign sign --key hanzo-kms://projects/my-org/keys/signing-key \
  registry.hanzo.ai/my-org/my-app:v1.0.0

# Verify a signature before pull
cosign verify --key cosign.pub registry.hanzo.ai/my-org/my-app:v1.0.0

Access Control

Registry access is managed through Hanzo IAM (hanzo.id). Permissions are scoped per namespace and repository:

RolePermissions
ReaderPull images, view scan results
WriterPush and pull images, manage tags
AdminAll of the above plus delete images, configure policies
# Grant a team read access to a namespace
curl -X POST -H "Authorization: Bearer $HANZO_API_KEY" \
  https://api.hanzo.ai/v1/registry/my-org/permissions \
  -d '{"team": "ml-engineers", "role": "writer"}'

Pull-Through Cache

Hanzo Registry can act as a transparent caching proxy for upstream registries. This reduces external bandwidth, improves pull latency, and provides resilience against upstream outages.

# Configured upstream mirrors
proxy:
  remotes:
    - name: docker-hub
      url: https://registry-1.docker.io
    - name: ghcr
      url: https://ghcr.io
    - name: gcr
      url: https://gcr.io

Pull through the cache by prefixing the upstream path:

# Pull from Docker Hub via Hanzo cache
docker pull registry.hanzo.ai/cache/library/nginx:1.27

# Pull from GHCR via Hanzo cache
docker pull registry.hanzo.ai/cache/ghcr/actions/runner:latest

Cached layers are stored on Hanzo S3 and expire based on configurable TTL (default: 7 days).

Garbage Collection

Hanzo Registry runs automated garbage collection to reclaim storage from:

  • Untagged manifests (orphaned by tag overwrites)
  • Unreferenced blobs (layers no longer referenced by any manifest)
  • Expired cache entries (pull-through cache TTL)

Garbage collection runs on a configurable schedule (default: daily at 03:00 UTC) and can also be triggered manually:

# Trigger garbage collection via API
curl -X POST -H "Authorization: Bearer $HANZO_API_KEY" \
  https://api.hanzo.ai/v1/registry/admin/gc

# View GC history
curl -s -H "Authorization: Bearer $HANZO_API_KEY" \
  https://api.hanzo.ai/v1/registry/admin/gc/history | jq .

CI/CD Integration

GitHub Actions

# .github/workflows/build.yml
name: Build and Push
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Login to Hanzo Registry
        uses: docker/login-action@v3
        with:
          registry: registry.hanzo.ai
          username: ${{ secrets.HANZO_REGISTRY_USER }}
          password: ${{ secrets.HANZO_REGISTRY_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: |
            registry.hanzo.ai/${{ github.repository }}:${{ github.sha }}
            registry.hanzo.ai/${{ github.repository }}:latest

      - name: Sign image
        run: |
          cosign sign --key env://COSIGN_KEY \
            registry.hanzo.ai/${{ github.repository }}:${{ github.sha }}
        env:
          COSIGN_KEY: ${{ secrets.COSIGN_PRIVATE_KEY }}

Hanzo Platform Pipeline

When deploying through Hanzo PaaS, images pushed to Hanzo Registry are automatically detected and deployed:

# hanzo.yaml
service:
  name: my-app
  image: registry.hanzo.ai/my-org/my-app
  deploy:
    trigger: push          # Deploy on every push to the registry
    tag_pattern: "v*"      # Only deploy semantic version tags
    scan_gate: high        # Block deploy if HIGH+ CVEs found
    verify_signature: true # Require valid Cosign signature

GitLab CI

# .gitlab-ci.yml
build:
  image: docker:27
  services:
    - docker:27-dind
  script:
    - echo "$HANZO_REGISTRY_TOKEN" | docker login registry.hanzo.ai -u hanzo --password-stdin
    - docker build -t registry.hanzo.ai/my-org/my-app:$CI_COMMIT_SHA .
    - docker push registry.hanzo.ai/my-org/my-app:$CI_COMMIT_SHA

Platform Images

The following Hanzo platform images are published to the registry and mirrored to ghcr.io/hanzoai/*:

ImageDescription
hanzoai/llm-gatewayLLM proxy for 100+ providers
hanzoai/consoleHanzo Console web application
hanzoai/console-workerConsole background worker
hanzoai/cloudCloud backend API
hanzoai/cloud-siteCloud marketing site
hanzoai/storageHanzo S3 server
hanzoai/commerceCommerce API
hanzoai/bot-siteHanzo Bot site
hanzoai/platform-studioPaaS Studio UI
hanzoai/platform-oauth-proxyPaaS OAuth proxy

PaaS

K8s-native GitOps deployments that pull from Hanzo Registry

Platform

Build pipelines and deployment management

S3

Object storage backend for registry blobs and model artifacts

KMS

Key management for image signing and secret injection

How is this guide?

Last updated on

Hanzo Edge

Global edge computing platform for low-latency AI inference, edge caching, serverless functions, and CDN -- powered by Cloudflare Workers.

Hanzo Visor

VM and container runtime for AI workloads with GPU passthrough, live migration, snapshot/restore, and Kubernetes CRI integration.

On this page

Hanzo Registry
Features
Architecture
Quick Start
Authenticate
Push a Container Image
Pull a Container Image
Multi-Architecture Build and Push
Image Management
Tagging Strategy
Listing Repositories and Tags
Deleting Images
Immutable Digests
Model Registry
Push a Model
Pull a Model
Supported Model Formats
Model Versioning
Security
Vulnerability Scanning
Image Signing
Access Control
Pull-Through Cache
Garbage Collection
CI/CD Integration
GitHub Actions
Hanzo Platform Pipeline
GitLab CI
Platform Images
Related Services