~20 min read

Manifest Field Reference

This page documents every field in the three Thumper-Run manifest types: .thumper.yaml (app), .model.yaml (model), and .pack.yaml (pack). Each table lists the field name, type, whether it is required, and a description.

Manifest Validator

Paste a manifest to validate required fields.

App Manifest (.thumper.yaml)

The app manifest describes how to install, configure, and launch an application. It is the most common manifest type and the one you’ll write first.

Minimal Example

.thumper.yaml

yaml

thumper: "1.0"
id: my-app
name: My App
version: 1.0.0
description: A simple demo application
author: you
type: app
runtime:
  type: python
  entry: app.py
  port: 8080

Quick Check: .thumper.yaml

name—Application display namerequired

description—One-line descriptionrequired

emoji—Single Unicode emojirequired

runtime.type—Runtime: python, docker, native, or noderequired

runtime.launch—Launch commandrequired

install_commands[]—At least one install commandrequired

health_check—Health check endpoint or scriptrequired

model_packs[]—Model packs (if app uses models)optional

patches[]—Platform patches for GPU/OS (optional)optional

screenshots[]—3-5 screenshots for catalog (optional)optional

gradient—Card gradient CSS class (optional)optional

App Metadata Fields

Top-level fields that identify the app and provide catalog metadata.

Field	Type	Required	Description
thumper	integer	Yes	Schema version. Always `1` for current manifests.
id	string	Yes	Unique identifier. Lowercase, hyphens allowed (e.g., `comfyui`).
name	string	Yes	Human-readable display name shown in the catalog.
version	string	Yes	SemVer version string (e.g., `1.2.3`).
description	string	Yes	Short description for the catalog card (1–2 sentences).
author	string	Yes	Author name or organization.
type	string	Yes	Must be `app`. Distinguishes from model/pack manifests.
area	string	No	Category: `image`, `chat`, `audio`, `video`, `code`.
tags	string[]	No	Searchable tags for the catalog (e.g., `["diffusion", "sdxl"]`).
license	string	No	SPDX license identifier (e.g., `MIT`, `GPL-3.0`).

Runtime Configuration

The runtime block controls how the app is launched, what port it listens on, and health-check behavior.

Field	Type	Required	Description
runtime.type	string	Yes	One of `python`, `docker`, `native`, `node`.
runtime.entry	string	Yes	Entry point script or binary (e.g., `main.py`, `./app`).
runtime.port	integer	Yes	Port the app listens on. Thumper-Run opens this in the WebView.
runtime.gpu_required	boolean	No	If `true`, shows a warning when no GPU is detected. Default: `false`.
runtime.health_check.path	string	No	HTTP path to poll until the app is ready (e.g., `/api/health`). Default: `/`.
runtime.health_check.timeout_secs	integer	No	Max seconds to wait for health check. Default: `120`.
runtime.web.launch_in_browser	boolean	No	If `true`, opens in the system browser instead of the Tauri WebView.
runtime.args	string[]	No	Extra command-line arguments passed to the entry point.
runtime.env	map	No	Environment variables injected at launch (key-value pairs).
runtime.graceful_timeout_ms	integer	No	Milliseconds to wait for graceful shutdown before SIGKILL. Default: `5000`.

Patches

Patches modify configuration files after installation. They enable GPU-specific settings, environment injection, and pip dependency filtering.

Field	Type	Required	Description
patches[].type	string	Yes	Patch type: `string_replace`, `json_merge`, `yaml_merge`, `env_set`, or `file_copy`.
patches[].condition.accelerator	string	No	Apply only when GPU matches: `cuda`, `rocm`, `mps`, `cpu`.
patches[].targets[].file	string	Yes	Relative path to the file to patch.
patches[].targets[].replacements[].old	string	Yes	Exact string to find in the target file.
patches[].targets[].replacements[].new	string	Yes	Replacement string.
patches[].description	string	No	Human-readable description of what this patch does.

The string_replace patch uses targets[].replacements[{old, new}] — not find/replace. Using the wrong field names silently does nothing.

Model Integration

These fields connect an app to model packs, specifying which models are needed and how they should be served.

Field	Type	Required	Description
pack_refs	string[]	No	References to external .pack.yaml manifests by ID.
model_refs	string[]	No	References to individual .model.yaml manifests by ID.
model_packs	object[]	No	Inline model pack definitions (embedded in the app manifest).
default_model_pack_id	string	No	ID of the pack to install by default for new users.
preferred_engine	string	No	LLM engine preference: `ollama`, `llamacpp`, `openai`.

Use ollama as the preferred engine for chat apps — it auto-pulls models and manages serving. Use llamacpp when you need direct GGUF file access or custom sampling parameters.

Model Manifest (.model.yaml)

A model manifest describes a single model weight file — its identity, format, source, and metadata. Model manifests are referenced by pack manifests or directly by app manifests.

Example

yaml

schema: thumper-model/v2
id: sdxl-base-1.0
name: Stable Diffusion XL Base 1.0
kind: diffusion-unet
format: safetensors
source:
  hf_repo: stabilityai/stable-diffusion-xl-base-1.0
  hf_file: sd_xl_base_1.0.safetensors
  sha256: 31e35c80fc4829d14f90153f4c74cd59c90b779f6afe05a74cd6120b893f7e5b

Quick Check: .model.yaml

id—Unique identifier (e.g., sdxl-base-v1)required

name—Human-readable model namerequired

version—Semantic version (e.g., 1.0.0)required

kind—ModelKind enum value (e.g., diffusion_unet)required

format—File format (safetensors, gguf, onnx)required

files[]—At least one file with path and sizerequired

architecture—Model architecture (optional)optional

license—SPDX license identifier (optional)optional

description—Short description (optional)optional

hf_repo_id—HuggingFace repository ID (optional)optional

Model Core Fields

Field	Type	Required	Description
schema	string	Yes	Must be `model/v1`.
id	string	Yes	Unique identifier for cross-referencing from packs.
name	string	Yes	Human-readable display name.
kind	ModelKind	Yes	The model architecture type (see Enums section below).
format	string	Yes	File format: `safetensors`, `gguf`, `onnx`, `bin`.
source	object	Yes	Download source with `hf_repo`, `hf_file`, and optional `sha256`.

Pack Manifest (.pack.yaml)

A pack manifest bundles multiple model manifests into a single installable unit. Packs are the primary way users interact with models — they install a pack, not individual weights.

Example

yaml

schema: thumper-pack/v2
id: sdxl-starter
display_name: SDXL Starter Pack
task_category: image-generation
models:
  - ref: sdxl-base-1.0
  - ref: sdxl-vae-fp16

Quick Check: .pack.yaml

id—Unique pack identifierrequired

name—Human-readable pack namerequired

version—Semantic versionrequired

models[]—At least one model referencerequired

default_variant—Default variant for auto-selectionrequired

platform_overrides—GPU-specific configs (optional)optional

min_vram_gb—Minimum VRAM requirement (optional)optional

description—Short description (optional)optional

Pack Core Fields

Field	Type	Required	Description
schema	string	Yes	Must be `pack/v1`.
id	string	Yes	Unique pack identifier for app manifest `pack_refs`.
display_name	string	Yes	Human-readable name shown in the model pack selector.
models[].ref	string	Yes	Reference to a model manifest by its `id` field.
task_category	string	No	Category for filtering: `image-generation`, `text-generation`, `audio-generation`, etc.

Enums & Constants

ModelKind (21 variants)

Variant	Description
diffusion-unet	UNet denoiser for Stable Diffusion models
diffusion-transformer	DiT / MMDiT transformer for SD3, Flux, etc.
vae	Variational autoencoder (encoder/decoder)
text-encoder	CLIP or T5 text encoder
lora	Low-rank adaptation weights
controlnet	ControlNet conditioning model
ip-adapter	IP-Adapter image prompt model
upscaler	Super-resolution upscaler (ESRGAN, etc.)
inpainting	Inpainting-specific model variant
llm	Large language model (GPT, LLaMA, Qwen, etc.)
embedding	Text embedding model for RAG
tts	Text-to-speech model
stt	Speech-to-text / transcription model
voice-conversion	Voice cloning / conversion (OpenVoice, RVC)
music-generation	Music generation model (ACE-Step, MusicGen)
video-generation	Video generation model (LTX, AnimateDiff)
image-classification	Image classifier or tagger
object-detection	Object detection model (YOLO, etc.)
segmentation	Image segmentation (SAM, etc.)
speaker-embedding	Speaker embedding / voice fingerprint
other	Catch-all for uncategorized model types

TaskCategory

Used in pack manifests to group packs by purpose.

Value	Description
image-generation	Diffusion-based image generation
text-generation	LLM chat and text completion
audio-generation	Music and sound generation
video-generation	Video synthesis and animation
voice	TTS, STT, and voice conversion

RuntimeType

Value	Description
python	Python venv with pip install
docker	Docker container with compose
native	Native binary (AppImage, .exe, .app)
node	Node.js with npm install

Complete Example

A full-featured app manifest showing metadata, runtime, patches, and model integration.

yaml

# .thumper.yaml — Full example
thumper: "1.0"
id: my-image-gen
name: My Image Generator
version: 1.0.0
description: Generate images with Stable Diffusion XL
author: thumper-community
type: app
area: image
tags: [diffusion, sdxl, image]
license: MIT
 
# Runtime configuration
runtime:
  type: python
  entry: main.py
  port: 8188
  gpu_required: true
  health_check:
    path: /api/health
    timeout_secs: 180
  args: ["--listen", "0.0.0.0"]
  env:
    PYTHONUNBUFFERED: "1"
  graceful_timeout_ms: 10000
 
# GPU-specific patches
patches:
  - type: string_replace
    condition:
      accelerator: rocm
    description: Enable ROCm for AMD GPUs
    targets:
      - file: config.yaml
        replacements:
          - old: "device: cuda"
            new: "device: rocm"
 
# Model packs
pack_refs: [sdxl-starter]
default_model_pack_id: sdxl-starter
preferred_engine: llamacpp

Key Takeaways

Every manifest starts with a schema version (thumper: "1.0" or schema: thumper-model/v2)
The id field must be unique across all manifests of the same type
Patches use old/new — not find/replace
Model packs bundle models into installable units — users install packs, not individual weights
Use pack_refs to reference external packs, model_packs to embed inline
The kind field uses the ModelKind enum with 21 variants

Advanced Reading

For the complete authoring guide with worked examples, see MODEL_MANIFEST_AUTHORING_GUIDE.md on GitHub (789 lines).

Learn More

Tutorial: App Manifest

Build a .thumper.yaml from scratch

Tutorial: Model Pack

Create model and pack manifests

Examples Gallery

Copy-paste starter manifests

Manifest Lifecycle

How manifests flow through the system