Running Apps with the Agent
The full app lifecycle — from finding to debugging — managed through conversation.
The App Lifecycle
The agent can manage every stage of an app's lifecycle:
| Stage | Tools | Example Prompt |
|---|---|---|
| Find | list_apps | "Find image generation apps" |
| Install | install_app | "Install ComfyUI" |
| Configure | file_read, file_edit | "Add ROCm support to the manifest" |
| Launch | launch_app | "Start it on port 8188" |
| Monitor | app_status, app_logs | "Is ComfyUI healthy?" |
| Debug | app_diagnose, crash_log_debug | "Why did it crash?" |
| Stop | stop_app | "Stop ComfyUI" |
Finding Apps
The list_apps tool searches the catalog with optional filters:
query— free text search ("chatbot", "image generation")tag— category filter ("llm", "image", "audio", "video")runtime— runtime type filter ("python", "docker", "native")
The app_status tool shows: process state, port, CPU %, memory usage in MB.
Installing Apps
The install_app tool accepts:
source_url(required) — git URL of the app repositoryapp_id(optional) — custom identifierbranch(optional) — specific branch to install
GPU-Aware Installation
For GPU-dependent apps, the agent automatically chains GPU detection before installing:
gpu_diagnose— detect GPU vendor, model, VRAM, driverhardware_status— check available VRAM and disk spaceinstall_app— install with GPU-appropriate configuration
The agent also checks available disk space before downloading and reports if there isn't enough room.
Troubleshooting Installation
If installation fails, ask the agent to debug:
install_debug— checks venv, dependencies, pathsapp_manifest_debug— validates manifest fields and cross-references
Launching & Stopping
The launch_app tool accepts:
app_id(required) — which app to launchport(optional, 1024-65535) — override default portenv(optional) — additional environment variables
The agent runs a health check after launch and reports the URL. It also detects GPU availability via gpu_diagnose and configures the app accordingly.
Port Conflicts
If the requested port is already in use, the agent detects the conflict and either suggests an alternative port or identifies which process holds it.
Stopping
The stop_app tool accepts:
app_id(required)force(optional, bool) — SIGKILL instead of SIGTERMtimeout_secs(optional) — wait before force kill
Use stop_app without force first — SIGTERM allows the app to clean up. Only use force: true if the process is stuck.
Debugging Issues
This is where the agent shines. Common symptoms and the tool chains used:
| Symptom | Prompt | Tools Used |
|---|---|---|
| App crashes on start | "Why does X keep crashing?" | app_diagnose → crash_log_debug |
| Out of memory (OOM) | "X keeps OOMing during VAE" | gpu_diagnose → hardware_status → app_logs → file_edit |
| GPU not detected | "My GPU isn't being used" | gpu_diagnose → gpu_test_pytorch → manifest_fix |
| Model not found | "Can't find the SDXL checkpoint" | model_list → search_files → file_edit |
| Wrong PyTorch | "Everything runs on CPU" | gpu_diagnose → gpu_test_pytorch → run_command (pip) |
| Slow generation | "Images take forever" | hardware_status → app_logs → gpu_diagnose |
Example: OOM on AMD APU
ComfyUI keeps OOMing during VAE decode on my AMD APU
[gpu_diagnose]
AMD gfx1150 (Radeon 890M), 8 GB shared VRAM
[hardware_status]
7.2 GB available, smart memory keeping 5.5 GB cached
[app_logs {app_id: "comfyui", level: "error"}]
torch.cuda.OutOfMemoryError at vae_decode
Thinking: Shared VRAM + smart memory = no room for VAE. Need --disable-smart-memory. FP16 causes NaN on AMD — must use BF16.
[file_edit] Updated .thumper.yaml: added --disable-smart-memory for amd_apu, switched to BF16
Fixed. Patch forces full model eviction before VAE. Never use FP16 on AMD APUs — it causes NaN in attention layers.
Example: GPU Not Used
My GPU isn't being used, everything runs on CPU
[gpu_diagnose]
NVIDIA RTX 3060, CUDA 12.1, driver 535.183
[gpu_test_pytorch {app_id: "comfyui"}]
torch.cuda.is_available() = False. torch version: 2.1.0+cpu
Thinking: CPU-only PyTorch installed. CUDA 12.1 → need cu121 index.
[manifest_fix {app_id: "comfyui"}]
Replaced hardcoded pip index with ${PYTORCH_INDEX_FLAG}
[run_command] pip install torch --index-url https://download.pytorch.org/whl/cu121
Reinstalled PyTorch with CUDA 12.1. Restart ComfyUI to pick it up.
Common Recipes
1. Quick Health Check
Prompt: "Is everything healthy?" — runs app_diagnose on each running app, reports status summary.
2. Find Optimal Model
Prompt: "Best SDXL for 8 GB?" — chains gpu_diagnose → model_list → hardware_status to recommend the best model for your hardware.
3. Migrate GPU Config
Prompt: "Switched from NVIDIA to AMD" — runs gpu_diagnose → manifest_validate → manifest_fix to update all GPU-specific configuration.
4. Generate Manifest
Prompt: "Package my Python app" — runs manifest_generate → manifest_validate to create and validate a .thumper.yaml.
5. Clean Up Disk
Prompt: "Running low on disk" — runs hardware_status → model_cache_diagnose to identify large models and duplicates.
These recipes work with any LLM backend. The agent picks the right tools based on your natural language request.