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 |
Publishing from New
You publish from Thumper itself: choose New › App, model or pack, fill in the steps and choose Sign and submit. You don't need a GitHub account or a pull request; your manifest and files live in a Thumper repository you own.
What to have ready
- Your
.thumper.yamlmanifest file, in the repository you publish from - Screenshots of the app installed and running
- The GPUs you tested on (e.g., "Tested on RTX 4090, CPU fallback"), for the hardware requirements step
- A link to the upstream app repository
- A model pack manifest if applicable
Quick Check: .thumper.yaml
From the terminal
thumper repo publish status shows what is listed and its review state. See Use the terminal for every seller command.
Review Process
Every listing, free or paid, is reviewed before it goes live. Your listing shows Submitted with the time you sent it, then In review, then Listed; we don't promise a review time. If something needs a fix, you see what to change and can send it again. See What Thumper reviews.
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 review
Once review passes, your app is listed in the App hub. Only the reviewed version goes live.
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 you send it for review; buyers keep the live version until the new one passes.
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 listing description.