2025-07-24 · 3 min read

Artifact Storage Layout for Self-Hosted Model Hubs

A self-hosted model hub becomes much easier to operate when the artifact layout is predictable. The files should be easy to locate, easy to version, and hard to mutate by accident. That means separating metadata from binary blobs and keeping release paths stable once they are published.

The simplest layout is versioned by slug and release number. A directory tree like adapters/<slug>/<version>/ makes it obvious where the current and historical artifacts live. Metadata can live one level above or alongside the artifact file, and sample outputs can live in a separate preview directory if needed.

artifacts/
  adapters/
    support-tone-v1/
      1.2.0/
        model.safetensors
        metadata.json
        changelog.md
      1.1.0/
        model.safetensors
        metadata.json

That layout gives the registry a clean rollback path. If a newer release turns out to be worse, the older one is still there and still referenced by a stable path. Users who downloaded the previous version can keep using it without confusion.

Temporary uploads should live somewhere separate from published artifacts. They are not the same thing. A temporary upload can be validated, scanned, and then moved or discarded. Published artifacts should only appear in the immutable release area once they have passed validation and been assigned a version.

The layout should also account for sample outputs and generated previews. Those files are useful for browsing, but they should not be mixed with the actual artifact. Keeping them separate makes it easier to clean caches, rebuild previews, and preserve the authoritative binary files.

Storage layout matters for cleanup too. If old temp uploads are clearly separated from releases, a cleanup job can remove them safely without touching published versions. That keeps the system small and manageable even on a modest server.

find artifacts/adapters -type f -name "*.safetensors" -size +100M

The registry should expose these paths only through the metadata layer, not by encouraging users to guess filenames. The internal structure can stay stable while the public API remains friendly. That is usually the best balance for a small hub.

It is also useful to store derived previews separately from source artifacts. Sample images, thumbnails, and rendered cards are helpful for browsing, but they should not be mixed with the authoritative binary files. That keeps cleanup simple and avoids accidental deletion of the important release objects.

If the registry supports mirrors or backups, the layout should make it easy to sync only the immutable release directories. Temporary uploads and cache directories do not need the same replication rules. That separation saves space and keeps operational logic easy to reason about.

The same layout discipline helps with permissions. If temporary uploads live in one place and published releases in another, the storage policy can be different for each area. That means the registry can clean up temp files aggressively while preserving released artifacts for as long as the catalog needs them.

A well-structured layout also makes debugging easier. When users ask where an artifact lives, the answer should be a stable path pattern rather than a special-case explanation. The less the operator has to improvise, the more predictable the registry becomes.

The last useful rule is to avoid encoding business logic in filenames. The path should tell you the slug and version, not hide extra meaning in a hand-typed suffix. Keeping the layout plain makes it easier to automate, easier to sync, and easier to document in the product itself.

ModelForgeLab can make this feel polished by keeping the storage layout boring and the user-facing catalog clean. That is a good sign in infrastructure: when the files are organized, the product is easier to trust.