A .model.yaml describes a single AI model — its source, format, hardware requirements, and integrity checks.

schema: thumper-model/v2
id: sdxl-base-1.0
name: Stable Diffusion XL Base 1.0
kind: checkpoint
format: safetensors
precision: fp16
architecture: sdxl
function: text-to-image
compatible_apps: [comfyui, stable-diffusion-webui, foocus]
 
source:
  type: huggingface
  repo: stabilityai/stable-diffusion-xl-base-1.0
 
install_dir: models/checkpoints
 
files:
  - path: sd_xl_base_1.0.safetensors
    sha256: "31e35c80fc4829d14f90153f4c74cd59c90b779f6afe05a74cd6120b893f7e5b"
    size_bytes: 6938078334
 
vram_gb: 6.5
disk_gb: 6.94
 
license:
  spdx: openrail++
  commercial: true
 
discovery_hints:
  filenames: [sd_xl_base_1.0.safetensors]
  size_range:
    min_bytes: 6900000000
    max_bytes: 7000000000

Key Concepts

• ModelKind: checkpoint, lora, controlnet, embedding, vae, llm, tts, video, audio, and 15+ more
• Sources: HuggingFace repos (type: huggingface), direct URLs (type: url), CivitAI, S3, local paths
• Integrity: SHA-256 hash on every file, verified on download
• Discovery hints: filename patterns + size ranges let the platform match local files to manifests without re-downloading
• License: SPDX identifier + commercial use flag for catalog filtering

100+ model manifests in examples/model-manifests/ covering image, video, audio, LLM, 3D, and face models.

A .pack.yaml bundles multiple models into a ready-to-use collection for a specific app or task.

schema: thumper-pack/v2
id: sdxl-starter
display_name: "SDXL Starter Pack"
kind: text-to-image
compatible_apps: [comfyui, foocus, stable-diffusion-webui]
 
models:
  - ref: sdxl-base-1.0
    role: primary-checkpoint
    required: true
  - ref: sdxl-refiner-1.0
    role: auxiliary-checkpoint
    required: false
  - ref: sdxl-vae-fp16-fix
    role: vae
    required: false
 
hardware:
  minimum:
    vram_gb: 6.5
    ram_gb: 16.0
    disk_gb: 14.0
  recommended:
    vram_gb: 12.0
 
presets:
  - name: Fast Generation
    models_needed: [sdxl-base-1.0]
  - name: High Quality
    models_needed: [sdxl-base-1.0, sdxl-refiner-1.0, sdxl-vae-fp16-fix]
 
platform_overrides:
  amd_apu:
    env:
      MIOPEN_FIND_MODE: "FAST"
    dtype_preference: "bf16"
    dtype_exclusions: ["fp16"]

Key Fields

• models[].role: primary-checkpoint, auxiliary-checkpoint, vae, speech-recognition, etc.
• models[].required: if true, app won't launch without this model; if false, it's optional
• hardware.minimum / recommended: VRAM/RAM/disk thresholds shown to users before download
• presets: named configs using subsets of models (users pick which preset to download)
• platform_overrides: per-GPU environment variables, dtype preferences, and exclusions

41 pack manifests in examples/model-manifests/ covering image, video, audio, LLM, 3D, and face pipelines.

Models often come in multiple precision formats trading quality for memory. The platform automatically picks the best variant for your GPU.

quantizations:
  - id: sdxl-base-fp16-pruned
    format: safetensors
    precision: fp16
    quality: high
    vram_gb: 6.0
    disk_gb: 6.46
    files:
      - path: sd_xl_base_1.0_0.9vae.safetensors
        size_bytes: 6938078334

Common Precision Formats

The platform checks available VRAM, filters to variants that fit, and picks the highest quality. Users can override in settings.

Complete field reference for all manifest types. See the schema files in schemas/ for JSON Schema definitions.

App Manifest (.thumper.yaml)

Model Manifest (.model.yaml)

Pack Manifest (.pack.yaml)

HuggingFace Integration

Thumper-Run discovers models from the local HuggingFace cache automatically. Use these manifest fields for HF-hosted models:

source:
  type: huggingface
  repo: stabilityai/stable-diffusion-xl-base-1.0
  revision: main    # branch or commit hash
  access: public    # public, gated, restricted
 
# Discovery hints for finding already-downloaded models
discovery_hints:
  filenames: [sd_xl_base_1.0.safetensors]
  hf_repos: [stabilityai/stable-diffusion-xl-base-1.0]
  size_range:
    min_bytes: 6900000000
    max_bytes: 7000000000

The discovery system links existing HF cache entries to app model directories via symlinks, avoiding duplicate downloads. Cache location: ~/.cache/huggingface/hub/ (override with HF_HOME).

CivitAI Integration

For models hosted on CivitAI, use the civitai source type or direct HTTPS URL:

source:
  type: civitai
  url: https://civitai.com/api/download/models/128713
 
# Or use direct HTTPS with fallback
source:
  type: https
  url: https://civitai.com/api/download/models/128713
  fallback:
    type: huggingface
    repo: mirror/model-name

When importing ComfyUI workflows, Thumper-Run automatically searches CivitAI by filename to resolve unknown models.