Create an App Manifest

~15 minIntermediateYou'll build: A complete .thumper.yaml manifest

In this tutorial you’ll write a complete .thumper.yaml manifest to package an existing Python AI app for the Thumper-Run catalog.

Before starting, make sure you have a working AI app with a git repository and a requirements.txt (or equivalent).

Step 1: What is a Manifest?

A .thumper.yaml manifest tells Thumper-Run everything it needs to install, configure, and launch your app. It covers:

Metadata — name, description, author, tags
Runtime — how to run the app (Python, Docker, native binary)
Install/Run — platform-specific shell commands
Models — what AI models to download and where to put them
Patches — GPU-specific config tweaks (AMD, Intel, CPU fallback)
Visuals — icon, screenshots, gradient colors for the catalog card

Step 2: Minimal Manifest

Start with the four required fields and build up from there:

.thumper.yaml

yaml

# my-app.thumper.yaml
thumper: "1.0"
id: my-image-app
name: My Image App
version: "1.0.0"
description: "A simple Stable Diffusion web UI"
author: your-username
type: "local web app"
area: image
license: MIT
license_type: "Free / Open Source"
tags: [image, stable-diffusion, web-ui]

The id must be lowercase alphanumeric with hyphens only. It becomes the unique identifier in the catalog.

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

Manifest Validator

Paste a manifest to validate required fields.

Area Values

Area	Examples
image	ComfyUI, Fooocus, Stable Diffusion WebUI
llm	Jan, SillyTavern, text-generation-webui
video	LTX Video, CogVideo
audio	ACE-Step, OpenVoice, Whisper
3d	Hunyuan3D, TripoSG
multimodal	Multi-modal agents
utility	Background removal, upscaling tools

Step 3: Runtime & Commands

Define how your app runs and what commands to execute on each platform:

yaml

runtime:
  type: python
  entry: app.py
  port: 7860
  gpu_required: true
  health_check:
    path: /
    timeout_secs: 120
  web:
    launch_in_browser: true
    localhost_url: "http://127.0.0.1:7860"
  output_dirs:
    - path: output
      name: "Generated Images"
      media_type: image
 
install:
  github_url: "https://github.com/you/my-image-app"
  commands:
    linux:
      - "pip install -r requirements.txt"
    macos:
      - "pip install -r requirements.txt"
 
run:
  commands:
    linux:
      - "python app.py --listen 0.0.0.0 --port 7860"

Runtime Types

Type	Isolation	Use When
python	Auto-created virtualenv	Most AI apps (ComfyUI, Fooocus, etc.)
docker	Container	Complex deps or multi-service apps
native	setsid() process group	Pre-built binaries (AppImage, .app)
node	node_modules	Node.js/Electron apps

The health_check path is critical — Thumper-Run polls this URL to know when your app is ready. If your app has no HTTP endpoint, set timeout_secs high and use a file-based check.

Step 4: Models & Packs

If your app needs AI models, declare them so Thumper-Run downloads them automatically:

Option A: Pack References (Recommended)

Reference existing model packs from the catalog:

yaml

pack_refs: [sdxl-starter, flux-schnell-starter]
default_model_pack_id: sdxl-starter

Option B: Inline Model Packs

Define models directly in the manifest:

yaml

model_packs:
  - name: "My App Models"
    models:
      - filename: model.safetensors
        download_url: "https://huggingface.co/user/repo/resolve/main/model.safetensors"
        sha256: "abc123..."
        dest_dir: models/checkpoints
        models_required: true

Option C: HuggingFace Cache Links

Symlink from the user’s existing HuggingFace cache:

yaml

model_links:
  - hf_repo_id: "stabilityai/sdxl-base-1.0"
    app_model_dir: models/checkpoints
    filename: sd_xl_base_1.0.safetensors

Always include sha256 hashes for model files. Thumper-Run verifies downloads and can detect corrupted files.

Step 5: GPU Patches

Different GPUs need different configs. Patches modify files or inject environment variables based on the detected accelerator:

yaml

patches:
  # AMD GPU: swap CUDA torch for ROCm torch
  - condition:
      accelerator: rocm
    phase: after_install
    operations:
      - type: pip_filter
        filter_packages: ["torch", "torchvision", "torchaudio"]
        install_instead:
          - "torch --index-url https://download.pytorch.org/whl/rocm6.2"
          - "torchvision --index-url https://download.pytorch.org/whl/rocm6.2"
 
  # CPU fallback: inject env var
  - condition:
      accelerator: cpu
    phase: before_launch
    operations:
      - type: env_inject
        env:
          FORCE_CPU: "1"

Accelerator Values

cuda — NVIDIA GPUs
rocm — AMD GPUs
mps — Apple Silicon (Metal)
xdna2 — AMD NPU (Ryzen AI)
cpu — CPU fallback

Patch Operations

string_replace — find/replace in config files
pip_filter — swap pip packages (e.g., CUDA torch → ROCm torch)
env_inject — set environment variables
json_merge — deep merge into JSON config files

Step 6: Visuals & Metadata

Make your app look good in the catalog:

yaml

visuals:
  emoji: "paint"
  image_url: "https://example.com/app-logo.png"
  screenshots:
    - "https://example.com/screenshot1.png"
    - "https://example.com/screenshot2.png"
  gradient:
    start: "#ffbdf2"
    end: "#c7eafd"
 
links:
  github: "https://github.com/you/my-image-app"
  docs: "https://my-image-app.readthedocs.io"
  discord: "https://discord.gg/invite-code"
 
requirements:
  min_ram_mb: 8192
  min_vram_mb: 6144
  min_disk_gb: 15
  gpu_required: true
  platforms: ["linux", "macos", "windows"]

The gradient colors appear as the card background in the catalog. Pick colors that match your app’s brand.

Step 7: Test & Publish

Validate your manifest locally before submitting:

Local Testing

Place your .thumper.yaml in the app’s git root
In Thumper-Run, go to Settings → Developer → Load Local Manifest
Point it at your manifest file
Test install, launch, and model download on your machine
Try it with different GPU configurations if possible

Submit to Catalog

Once tested, submit through the publishing workflow:

Read the Publishing Guide for the full checklist
Prepare your catalog assets (icon, screenshots, description)
Submit via the catalog submission form
A reviewer tests install + launch on multiple platforms

Key Takeaways

4 required fields: thumper, id, name, version
Use pack_refs to reference existing model packs instead of inline model_packs
Always include health_check — Thumper needs it to know when your app is ready
Test with both GPU and CPU fallback before submitting
Patches let you swap CUDA torch for ROCm/MPS/CPU without separate manifests

Next Steps

Create model packs — see the Model Pack Tutorial
Full manifest reference — App Developer Guide
GPU-specific optimization — Troubleshooting Guide

Learn More

Model Pack Tutorial

Create model and pack manifests

App Developer Guide

Full manifest schema reference

Publishing Guide

Submit to the catalog

ComfyUI on Thumper

Per-app guide example