Thumper-Run manages the full lifecycle of AI apps — from installation to launch to cleanup.

Browsing the Catalog

The catalog contains 47 apps across image generation (ComfyUI, Fooocus, Stable Diffusion), LLMs (Open WebUI, Jan, Ollama), audio (OpenVoice, ACE-Step), video (LTX Video, HunyuanVideo), and workflow tools (Langflow, AnythingLLM). Each app shows its GPU requirements, disk size, and user ratings.

Installing an App

Click Install on any app card. The platform automatically:

1. Clones the source repository (if github_url is set)
2. Creates an isolated Python environment (for Python apps)
3. Runs platform-specific install commands (selecting CUDA/ROCm/CPU as appropriate)
4. Downloads required model packs (if pack_refs is set)

Installation progress shows per-step status. If a step fails, the error is shown with the full command output.

Launching and Health Checks

After installation, click Launch. The platform starts the app process, monitors its health check endpoint (typically GET / with a 30–120s timeout), and shows the app UI once healthy. Apps that set launch_in_browser: true open in your system browser; others use the built-in webview.

Process Management

Running apps can be stopped, restarted, or force-killed. The platform handles:

• Crash recovery: automatic restart with backoff
• Orphan cleanup: child processes are killed when the parent exits
• Port management: each app gets its configured port, conflicts are detected at launch

The console is a dashboard for monitoring all running apps. It shows real-time status, resource usage, and provides quick controls without navigating to each app individually.

What the Console Shows

Console preferences (font size, line wrapping, timestamp format) are stored in your CRDT user document and sync across devices.

Models are the weights files that AI apps need to run. Thumper-Run discovers, downloads, and organizes them automatically.

Model Discovery

The platform scans three locations for existing models:

• HuggingFace cache (~/.cache/huggingface/hub/) — repos you've already downloaded via huggingface-cli or other tools
• Ollama library (~/.ollama/models/) — models pulled with ollama pull
• Thumper store (~/.local/share/tr-desktop/models/) — models downloaded through the platform

Discovered models are matched to manifests using filename patterns and file size ranges, so the platform knows what you already have.

Downloading Models

When an app needs a model you don't have, the platform downloads it with:

• Streaming downloads with progress tracking (speed, ETA, percentage)
• Resume support — interrupted downloads continue from where they left off (.part files)
• SHA-256 verification — every file is verified against the hash in its manifest
• VRAM-aware selection — if a model has multiple quantization variants, the platform picks the highest quality that fits in your available VRAM

Storage Management

View per-model and per-app disk usage in Settings → Storage. The cleanup tool identifies:

• Duplicate models across locations (e.g., same weights in both HF cache and Thumper store)
• Models not referenced by any installed app
• Partially downloaded files that can be safely removed

Beta Thumper-Run includes a built-in AI assistant that can diagnose GPU issues, repair manifests, manage models, and automate common tasks. It has access to 28 specialized tools organized into 6 categories.

What Can the Agent Do?

Agent Templates

Tool Approval

Tools are classified by safety level:

• SafeAuto-run: gpu_detect, model_search, system_info, file_read, port_scan, vram_report
• ConfirmRequire approval: app_install, app_launch, file_write, model_download, manifest_generate
• DangerousExplicit confirmation + warning: app_uninstall, file_delete, process_kill

Built-in Code Editor

The agent can open files in a built-in code editor with:

• Syntax highlighting for Python, YAML, JSON, TOML, Bash, and 20+ languages
• Undo / Redo with full history (Ctrl+Z / Ctrl+Shift+Z)
• File tree with resizable drag handle for navigating app directories
• Search across files (Ctrl+Shift+F) with regex support
• Diff view — when the agent edits a file, the before/after diff is shown for approval

The editor is useful for inspecting and editing manifests, ComfyUI workflow JSON, config files, and app source code without leaving the platform.

Session Persistence

Agent sessions persist across app restarts. The conversation history, tool results, and generated code are stored in the CRDT document and synced across devices. Switching between apps preserves each app's agent context independently.

Example Conversation

Stable The cross-app image gallery automatically collects generated images from all installed AI apps into a single, searchable view. No manual organization needed.

How It Works

1. File watcher monitors every installed app's output directory for new images in real-time
2. Metadata extraction reads embedded generation parameters from the image file itself
3. Indexing builds a searchable database so you can find images by any metadata field

Supported Metadata Formats

Search and Filter

The gallery supports full-text search across prompts and metadata. Filter by:

• Source app (show only ComfyUI images, or only Fooocus, etc.)
• Model name (e.g., all images generated with SDXL Base)
• Date range
• Prompt keywords
• Favorites (star images to find them quickly)

IPC Commands

• gallery_scan_outputs — trigger a full scan of all app output directories
• gallery_list_images — paginated list with optional filters (app, date, prompt)
• gallery_get_image — full metadata for a single image including extracted generation parameters

Beta Pair devices for supported multi-device workflows. Pairing uses QR codes and X25519 key agreement, but pairing alone does not establish a current private E2EE guarantee for synced content.

Pairing Flow

What Syncs?

• Settings & preferences — theme, model preferences, agent sessions
• App install state — which apps are installed, their launch configs
• Reviews & ratings — your app reviews sync across devices
• Gallery favorites — starred images visible on all devices
• Private documents — private E2EE modes remain gated and should not be treated as a current sync guarantee

Device Management

In Settings → Devices you can:

• Rename devices for easy identification ("Living Room PC", "Work Laptop")
• Revoke a device to remove it from your linked-device list when you no longer use it
• View sync status — see last sync time, pending changes, and connection state per device

Thumper-Run stores data across several directories. Understanding the layout helps with debugging, backup, and disk management.

Application Data

~/.local/share/tr-desktop/
├── apps/                   # Installed app repos + venvs
│   ├── comfyui/
│   ├── open-webui/
│   └── jan/
├── models/                  # Downloaded model weights
│   ├── sdxl-base-1.0.safetensors
│   └── Qwen3-4B-Q4_K_M.gguf
├── logs/                    # Per-app log files
├── crdt/                    # CRDT database (SQLite)
└── gallery/                 # Generated image metadata

HuggingFace Cache

~/.cache/huggingface/hub/
├── models--stabilityai--sdxl-base-1.0/
│   └── snapshots/{hash}/
│       └── sd_xl_base_1.0.safetensors
├── models--Qwen--Qwen3-4B-GGUF/
└── models--openai--whisper-large-v3/

The HuggingFace cache is shared with other tools (huggingface-cli, diffusers, transformers). Thumper-Run reads from it but never deletes files here.

Ollama Models

~/.ollama/models/
├── manifests/registry.ollama.ai/
│   └── library/{model}/latest
└── blobs/
    └── sha256-{hash}

Configuration

~/.config/tr-desktop/
├── settings.json            # App preferences
└── identity/                # Device keys (E2EE)

Keyboard shortcuts work in the desktop app. Some shortcuts are context-dependent.

Global

Code Editor

Gallery

Console