Publishing Workflow
This guide walks you through the process of packaging an AI app and submitting it to the Thumper-Run catalog. For manifest field reference, see App Manifests. For model packaging, see Model Manifests.
What Makes a Good Catalog App
- One-click install — users should go from catalog to running app without manual steps
- GPU fallback — gracefully degrade from CUDA → ROCm → CPU when possible
- Health check — respond to the health endpoint so the launcher knows when you're ready
- Clean shutdown — release GPU memory and ports when stopped
examples/thumper-manifests/minimal.thumper.yaml as your template. It contains only the required fields.Pre-Flight Checklist
Before submitting, verify your manifest covers these essentials:
| Item | Required | Notes |
|---|---|---|
| Health check configured | Yes | See Design Patterns |
| GPU fallback chain | Yes | CUDA → ROCm → CPU via platform patches |
| No hardcoded paths | Yes | Use ${env} substitution for all paths |
| Model pack defined | If applicable | Required if app uses downloadable models |
| serde(default) on optional fields | Yes | Ensures backward compatibility |
| License field set | Yes | See model license guidance |
Testing Your App
Thorough testing before submission prevents rejection and ensures a good user experience. Test the full lifecycle, not just launch.
Cold Install Test
Start from a completely clean state — no cached virtualenv, no pre-downloaded models. This is what users experience on first install.
- Remove any existing app directory and cached models
- Run the install from your manifest file
- Verify all dependencies download and install correctly
- Launch the app and confirm the health check responds within the configured timeout
GPU Vendor Testing
If possible, test on at least two GPU backends (e.g., CUDA + CPU, or ROCm + CPU). At minimum, verify the CPU fallback path works.
Process Cleanup Verification
After stopping your app, verify no orphan processes remain. Child processes that escape cleanup will consume GPU memory and block ports.
ss -tlnp | grep PORT to verify the port is released after stopping the app.--lowvram on APU or Apple Silicon — it causes 5% GPU utilization by shuffling data through the same physical RAM. Never use FP16 on AMD APU (gfx1150) — it causes NaN in DiT attention.Preparing Assets
Your manifest includes visual assets that appear in the catalog and app launcher. Follow these specifications for best results:
| Field | Spec | Notes |
|---|---|---|
| emoji | Unicode, renders at 24px and 16px | Test at both sizes for legibility |
| gradient | Tailwind CSS classes | Must contrast with white text overlay |
| icon_url | 512×512 min, PNG with alpha | Must be legible when downscaled to 32×32 |
| cover_image | 1200×630 recommended | Used for social/OG sharing and catalog cards |
| screenshots | PNG, 1280×720 min | Actual app screenshots, not renders |
| gradient.start | Hex, — | Card background gradient start color |
| gradient.end | Hex, — | Card background gradient end color |
Submitting Your PR
The catalog is managed via GitHub. To add your app, submit a pull request with your manifest and any supporting files.
Branch Naming
Use the convention catalog/add-{app-id} for new apps or catalog/update-{app-id} for updates.
What to Include
- Your
.thumper.yamlmanifest file - Screenshots or test evidence showing successful install and launch
- List of GPUs tested on (e.g., "Tested on RTX 4090, CPU fallback")
- Link to the upstream app repository
- Model pack manifest if applicable
Quick Check: .thumper.yaml
Commit Message Convention
Use the format: feat(catalog): add {app-name} v{version} for new apps, or fix(catalog): update {app-name} to v{version} for updates.
Review Process
After you submit your PR, the maintainers will review your manifest. Expect a response within 3–5 business days.
Common Rejection Reasons
| Issue | How to Fix |
|---|---|
| Missing health check | Add a health_check section with endpoint and timeout |
| Hardcoded paths | Replace absolute paths with ${env} variable substitution |
| No GPU fallback | Add platform patches for at least CUDA and CPU backends |
| Missing license | Set the license field in your manifest |
| Orphan processes on stop | Ensure child processes are cleaned up; use setsid() for process groups |
After Merge
Once merged, your app appears in the catalog within the next sync cycle. The catalog version is automatically bumped.
Maintaining Your App
Apps in the catalog need periodic maintenance as upstream projects release new versions and GPU backends evolve.
Version Bumps
When the upstream app releases a new version, update the version and source.ref fields in your manifest. Test the new version through the same cold-install process before submitting.
Patch Adjustments
Upstream changes may break existing patches (e.g., a config file format change). Monitor the upstream release notes and update your string_replace patches accordingly.
Responding to Reviews
Users can leave reviews and ratings for your app. Check the reviews periodically and address common issues by updating your manifest or adding troubleshooting notes to your PR.