Manifest Lifecycle

A manifest flows through five stages from authoring to running.

1. Authoring

A developer writes a YAML manifest describing the app, its models, and GPU patches. This can be done by hand or generated by the Thumper AI assistant.

2. Validation

When the manifest is submitted to the catalog (or loaded locally), Thumper-Run validates all required fields, checks that model references resolve, and verifies the schema version.

3. Resolution

At install time, the resolver expands pack_refs into concrete model lists, selects VRAM-appropriate model variants, and builds a download plan.

4. Installation

The install pipeline clones the app repo, creates a venv (or pulls a Docker image), downloads models with resume support, and applies GPU-conditional patches.

5. Launch

At launch, the manifest drives process spawning: entry point, port, environment variables, health-check polling, and WebView or browser opening.

Minimal Manifest

thumper: 1
id: hello-world
name: Hello World
version: 1.0.0
description: A minimal demo app
author: you
type: app
runtime:
  type: python
  entry: app.py
  port: 8080

Thumper-Run uses three kinds of manifests, each with a distinct purpose.

• Reproducible Installs — Same manifest, same result on every device. No “works on my machine” problems.
• Cross-Platform — One manifest handles Linux, macOS, and Windows with GPU-conditional patches.
• Composable — App manifests reference pack manifests, which reference model manifests. Mix and match.
• Version Controlled — Manifests are plain YAML files that live in Git. Review, diff, and roll back changes.
• AI Assistable — The Thumper AI agent can generate and validate manifests from natural-language descriptions.

When a manifest fails validation, Thumper-Run reports a specific error. Here are the most common ones:

A manifest moves through five states from creation to publication:

  Draft  -->  Validated  -->  Submitted  -->  Reviewed  -->  Published
    |            |               |               |
    v            v               v               v
  (edit)    (auto-check)    (queue for       (approve/
             pass/fail       review)          reject)

State Descriptions

• Draft — Author is editing. Can be modified freely.
• Validated — Automated checks passed (schema, references, model URLs). Ready for submission.
• Submitted — Entered the review queue. Author cannot edit until review is complete.
• Reviewed — A maintainer has approved or requested changes. If rejected, returns to Draft.
• Published — Visible in the catalog. Users can install it.

• Pin model versions — Always specify an exact model version or SHA-256 hash. "latest" tags can break installs when upstream models change.
• Document GPU patches — Add comments in the YAML explaining why each GPU-conditional patch exists. Future maintainers (including you) will thank you.
• Test on multiple platforms — GPU patches, path separators, and permissions differ across Linux/macOS/Windows. Test at least two.
• Use pack_refs for shared models — If multiple apps use the same model (e.g., SDXL base), reference a shared pack instead of duplicating the model definition.
• Keep manifests in version control — Manifests are plain YAML. Store them in Git alongside the app code for full traceability.
• Validate before submitting — Run the validation agent tool locally to catch errors before the review queue.

For the complete field-by-field reference, see the Manifest Field Reference page. For hands-on tutorials, try building an app manifest or creating a model pack.

The manifest system is implemented in Rust with strict validation at every stage. Invalid manifests fail loudly with specific error messages rather than silently misbehaving.