App Manifests

A .thumper.yaml manifest describes how to install, configure, and launch an AI app. Every app in the catalog is defined by one.

Minimal Example

thumper: "1.0"
id: my-app
name: My App
version: "0.1.0"
runtime:
  type: python
  entry: main.py

Full Example (ComfyUI)

thumper: "1.0"
id: comfyui
name: ComfyUI
version: "1.0.0"
description: "The most powerful and modular stable diffusion GUI and backend"
author: comfyanonymous
type: "local web app"
area: image
tags: [image, text-to-image, node-based, stable-diffusion, comfyui]
 
runtime:
  type: python
  entry: main.py
  port: 8188
  gpu_required: true
  health_check:
    path: /
    timeout_secs: 60
 
requirements:
  min_ram_mb: 16384
  min_vram_mb: 8192
  min_disk_gb: 100
  gpu_required: true
 
install:
  github_url: "https://github.com/comfyanonymous/ComfyUI"
  commands:
    linux:
      - "pip install torch torchvision torchaudio ${PYTORCH_INDEX_FLAG}"
      - "pip install -r requirements.txt"
 
pack_refs: [sdxl-starter]

Key Fields

Field	Required	Description
thumper	Yes	Schema version, always "1.0"
id	Yes	Unique lowercase identifier
name	Yes	Display name
version	Yes	Semver version
runtime	Yes	How to run: type, entry, port
install	—	GitHub URL + per-platform install commands
requirements	—	RAM, VRAM, disk, GPU, platform constraints
pack_refs	—	Model pack IDs to install
visuals	—	Emoji, icon, gradient, screenshots
links	—	Homepage, GitHub, docs URLs
patches	—	Accelerator-specific config patches

47 complete manifests in examples/thumper-manifests/ — including ComfyUI, Open WebUI, Fooocus, FaceFusion, Jan, and more.

Runtime Types

The runtime block tells the platform how to start your app. Four types are supported.

Python (most common)

runtime:
  type: python
  entry: main.py
  port: 8188
  gpu_required: true
  health_check:
    path: /
    timeout_secs: 60

Docker (AnythingLLM)

runtime:
  type: docker
  port: 3001
  image: mintplexlabs/anythingllm:latest
  health_check:
    path: /
    timeout_secs: 30
  web:
    launch_in_browser: true

Node (SillyTavern)

runtime:
  type: node
  entry: server.js
  port: 8000
  health_check:
    path: /
    timeout_secs: 30
  web:
    launch_in_browser: false

Native (Jan)

runtime:
  type: native
  entry: jan.AppImage
  gpu_required: false

Health Checks

path: HTTP endpoint to poll (usually /, some apps use /readyz)
timeout_secs: max seconds to wait for healthy response (30–120s typical)
Platform polls every 2 seconds until a 200 OK or timeout

Web Launch Modes

launch_in_browser: true — opens in system browser
launch_in_browser: false — displays in built-in webview

Environment Variables

${PYTORCH_INDEX_FLAG} — auto-set to the appropriate PyTorch index URL for your GPU (CUDA for NVIDIA, ROCm for AMD, empty for CPU).

Install Commands

Install commands run after the source code is cloned. They're organized by platform and GPU type.

install:
  github_url: "https://github.com/comfyanonymous/ComfyUI"
  commands:
    linux:
      - "pip install torch torchvision torchaudio ${PYTORCH_INDEX_FLAG}"
      - "pip install -r requirements.txt"
    windows:
      cuda:
        - "pip install torch torchvision torchaudio ${PYTORCH_INDEX_FLAG}"
        - "pip install -r requirements.txt"
      directml:
        - "pip install torch-directml"
        - "pip install torchvision torchaudio"
        - "pip install -r requirements.txt"
      cpu:
        - "pip install torch torchvision torchaudio ${PYTORCH_INDEX_FLAG}"
        - "pip install -r requirements.txt"

How It Works

If github_url is set, the repo is cloned first
Platform is detected (linux/windows/macos)
On Windows, GPU type is detected (cuda/directml/intel/cpu) and the matching command list runs
On Linux/macOS, the flat command list runs (GPU selection happens via ${PYTORCH_INDEX_FLAG})
Commands run sequentially — if any fails, installation stops with the error output

Platform Patches

Patches modify app configuration files after installation to optimize for specific hardware or integrate with Thumper-Run.

env_inject — Set Environment Variables

From Open WebUI manifest:

patches:
  - id: openwebui-ollama-connection
    description: "Point Open WebUI to local Ollama instance"
    phase: launch
    type: env_inject
    vars:
      OLLAMA_BASE_URL: "http://localhost:11434"
      WEBUI_AUTH: "False"

json_merge — Merge Into JSON Config

From SillyTavern manifest:

patches:
  - id: sillytavern-local-llm-connection
    description: "Pre-configure OpenAI-compatible endpoint"
    phase: launch
    type: json_merge
    targets:
      - file: "data/default-user/settings.json"
        content: |
          {
            "main_api": "openai",
            "oai_settings": {
              "chat_completion_source": "custom",
              "custom_url": "http://localhost:11434/v1"
            }
          }

string_replace — Find and Replace in Text

From SillyTavern manifest:

patches:
  - id: sillytavern-disable-browser-launch
    description: "Disable built-in browser launch"
    phase: post_install
    type: string_replace
    targets:
      - file: "config.yaml"
        replacements:
          - old: "enabled: true"
            new: "enabled: false"

Patch Fields

phase: post_install (runs once after install) or launch (runs every time the app starts)
applies_when.accelerator: any, amd_apu, nvidia, etc.
fatal: if true, app won't launch if patch fails
priority: lower numbers run first

Design Patterns

Proven patterns for building reliable Thumper manifests, and anti-patterns to avoid.

Pattern: GPU Fallback Chain

Define install commands per GPU vendor with CPU as the final fallback. The platform picks the best match.

yaml

install:
  commands:
    cuda: pip install torch --index-url https://download.pytorch.org/whl/cu124
    rocm: pip install torch --index-url https://download.pytorch.org/whl/rocm6.2
    cpu:  pip install torch --index-url https://download.pytorch.org/whl/cpu

Pattern: LLM Engine Selection

Declare which LLM engine your app uses with preferred_engine. The user can override this in Settings → LLM Engine.

yaml

# For Ollama-based apps (chat UIs like Open WebUI, SillyTavern)
preferred_engine: ollama
dependencies:
  ollama: true
  ollama_models: ["qwen3:8b"]
runtime:
  env:
    OLLAMA_BASE_URL: "http://localhost:${ollama_port}"
 
# For llama.cpp apps (embedded inference, agents)
# preferred_engine: llamacpp
# Models referenced via model_packs or pack_refs (GGUF files)
 
# For cloud API apps
# preferred_engine: openai
# User provides API key in Settings

Use ollama for chat apps — it manages models for you and auto-starts. Use llamacpp for embedded inference or CPU-only deployments where you bundle the GGUF file directly.

Pattern: Health Check with Backoff

Configure a generous timeout for first-run startup (model loading can be slow), with a fast interval for subsequent checks.

yaml

runtime:
  health_check:
    endpoint: "/"
    timeout: 120         # seconds to wait on first launch
    interval: 5          # seconds between checks
    healthy_threshold: 1  # successful checks before "ready"

Pattern: Patch Layering

Apply patches in order: base config first, then GPU-specific overrides. Use string_replace for targeted edits.

yaml

patches:
  - type: string_replace
    targets:
      - file: config.json
        replacements:
          - old: '"gpu_layers": 0'
            new: '"gpu_layers": 99'

Pattern: Model Pack Composition

Build packs by referencing individual model manifests. Each model specifies its own download URL and hash.

yaml

# my-app.thumper.yaml
pack_refs:
  - sdxl-starter       # references sdxl-starter.pack.yaml
  - openvoice-v1-base  # references openvoice-v1-base.pack.yaml

Pattern: Supervisor Process

For apps with multiple processes (e.g., backend + frontend), use a supervisor entry point.

yaml

runtime:
  type: python
  entry: supervisor.py   # manages child processes
  port: 8080             # primary health check port

Anti-Patterns

Anti-Pattern	Problem	Fix
Hardcoded GPU paths	Breaks on other GPU vendors	Use platform variables and fallback chain
Missing health check	App shows as "running" before ready	Always set health_check.endpoint
FP16 on AMD APU	NaN in DiT attention (gfx1150)	Force BF16 via patch or env var
Fire-and-forget process	Orphan processes on crash	Use setsid() and process groups
Blocking download in UI	Frozen UI during large downloads	Use async with progress events
--lowvram on APU	5% GPU util (same physical RAM)	Never use on shared memory systems

Contributing

Submit your AI app, model, or pack to the Thumper-Run catalog.

Submit Your App

Fork the repository
Create a .thumper.yaml manifest (start from the minimal example in Quickstart)
Validate with thumper validate ./my-app.thumper.yaml
Test on at least two GPU vendors (NVIDIA + AMD, or NVIDIA + CPU)
Submit a PR to examples/thumper-manifests/

Testing Checklist

Install completes without errors on Linux and at least one other platform
Health check endpoint responds within the configured timeout
Model packs download and verify (if pack_refs is set)
GPU selection works correctly (CUDA/ROCm/CPU fallback)
Patches apply cleanly on a fresh install

Model & Pack Contributions

Same workflow: create a .model.yaml or .pack.yaml, validate, test download + SHA-256 verification, and submit a PR to examples/model-manifests/.

Learn More

App Manifest Tutorial

Step-by-step manifest creation

Model Developer Guide

Model and pack manifest reference

ComfyUI on Thumper

Per-app guide with GPU tips

Publishing Guide

Submit to the catalog