rhub — RunningHub Precision Control Center

Advanced image and video generation control center. Features AI-orchestrated prompt engineering from 300 photogenic locations, multi-model generation (FLUX.1-dev via RunningHub, Z-Image via RunPod Serverless, and FLUX.2-klein via RunPod Serverless), multi-LoRA additive blending, sequential batch queuing, selectable RunningHub image upscaling with LSB steganography support, image enhancement via fal.ai Phota and RunningHub workflows, video creation via fal.ai Seedance 2.0, and real-time polling.

rhub is a specialized SvelteKit-based dashboard that transforms simple subject descriptions into high-quality, LoRA-consistent imagery and video. It solves the "repetition problem" in AI generation by bridging expert prompt engineering (Gemini/Qwen) with multiple synthesis pipelines.

Key Features

• Multi-Model Generation — Switch between FLUX.1-dev (RunningHub), Z-Image (RunPod Serverless), and FLUX.2-klein (RunPod Serverless) from the Generate tab. The same AI prompt engineering pipeline feeds all three models.
• Multi-LoRA Blending — Both Z-Image and FLUX.2-klein support a dynamic LoRA Stack. Load multiple adapters in parallel with per-LoRA strength control and additive blending. A curated preset dropdown is populated from a build-time config file — pick a style or enter any custom URL.
• Expert Orchestration — Google Gemini 3 Flash or RunPod Qwen 30B synthesizes detailed prompts via a 2-step process: location selection + AI composition. Each model has a specialized Prompt Director tuned for its strengths.
• Z-Image Detail Pipeline — Z-Image uses selectable spandrel-backed detail upscalers (nomos_webphoto, nomos_webphoto_esrgan, or purephoto) and defaults to an img2img hires-fix pass that upscales first, then lightly re-diffuses to clean super-resolution artifacts.
• FLUX.2-klein Support — 9B-parameter undistilled flow-match transformer by Black Forest Labs, with quality presets, multi-LoRA support, optional detail refinement (2nd pass), and server-side upscaling.
• Image Upscaling — Batch upscale images using selectable RunningHub workflows: the original 2K Upscale workflow or the RunningHub API Upscale app. Handles intermediary storage via S3 (e.g., Backblaze B2) with automatic presigned URL generation.
• Image Enhancement — Enhance images via the Enhance tab using fal.ai Phota or three RunningHub workflows (standard Enhance, Enhance+Detail, or HD Detailer). Accepts image file uploads or URLs. RunningHub uploads are temporarily hosted through S3 presigned URLs before workflow submission. Any generated image in the queue can be sent directly to Enhance.
• Video Creation — Create videos via the Create Video tab using fal.ai Seedance 2.0 (bytedance/seedance-2.0/reference-to-video). Supports up to 9 reference images, up to 3 reference videos, up to 3 reference audio files, 480p/720p/1080p resolution, duration, aspect ratio, audio generation, seed, and optional end-user ID. Inputs are validated locally against fal.ai's schema before submit to prevent avoidable 422 errors. FAL jobs are polled asynchronously and videos are saved to the output volume. Any generated image in the queue can be sent directly to the video tab as a reference image.
• LSB Steganography (TT-Decoder/Encoder) — Built-in TypeScript support for both extracting hidden data from generated images and embedding data into carrier images for secure upscale processing.
• Persistent Sequential Queue — Bypasses RunningHub's single-task limitation with a robust client-side queue. Captures full form state (LoRA, model, output dir, API keys) per task, survives page refreshes, and processes jobs one-by-one.
• Environment-backed API Keys — API keys can be pre-configured in .env and are automatically used as defaults. UI fields override them on a per-session basis.
• Modern Tabbed UI — 4-tab segmented control interface (Generate, Upscale, Enhance, Create Video) with smooth sliding indicators and responsive mobile layout.
• 300 Curated Locations — Module-level Fisher-Yates shuffled queue of 300 unique locations ensures zero repetition across large batches.
• Flexible Dimensions — 9 aspect ratio presets for FLUX.1-dev and Z-Image (16px-aligned auto-calculation), plus 12 dedicated aspect ratio presets for FLUX.2-klein (landscape, square, and portrait — all ~1K resolution, 32px-aligned).
• Containerized Deployment — Fully Dockerized with environment-based configuration for secrets and server limits. The app runs inside Docker and is accessed through NPM Proxy Manager on the shared Docker network; no app port is exposed directly to the local host.

Architecture

The application runs as a single SvelteKit container. API routes handle server-side logic including AI prompt synthesis, S3 uploads, RunningHub interaction, direct RunPod Serverless calls, fal.ai enhancement, and fal.ai video generation. Images and videos are served directly from a Docker-mounted volume to prevent caching issues and ensure persistence.

Data Flow

Generation Flow — FLUX.1-dev (RunningHub)

1. User selects FLUX.1-dev model, provides subject characteristics, LoRA URL, and API keys.
2. Tasks are added to the Persistent Queue.
3. Background processor picks the next task:
   • AI selects a location and generates a vivid composition.
   • AI synthesizes the final detailed FLUX.1-dev prompt.
4. Dimensions are calculated and the task is submitted to RunningHub.
5. The client polls /api/check for status, downloads the result, and optionally decodes hidden data.

Generation Flow — Z-Image (RunPod Serverless)

1. User selects Z-Image model and configures subject characteristics and an optional LoRA Stack.
2. Tasks are added to the Persistent Queue with the same AI prompt engineering pipeline.
3. Background processor picks the next task:
   • AI synthesizes the prompt (same Gemini/Qwen pipeline as FLUX.1-dev). Trigger words from all LoRAs in the stack are automatically aggregated.
4. Job is submitted to the RunPod Z-Image Serverless endpoint (/run) using the preferred multi-LoRA loras array when LoRAs are configured.
5. The request includes the selected upscale_model. The default is nomos_webphoto, a natural RealPLKSR photo upscaler; nomos_webphoto_esrgan and legacy purephoto are also available.
6. By default, the worker runs img2img Hires-Fix (second_pass_enabled=true): it upscales the base image by 1.25×, then re-diffuses through Z-Image img2img at strength 0.42. A 1024×1024 request returns a 1280×1280 PNG by default.
7. If Hires-Fix is disabled, the worker can still run a single-pass detail upscale (upscale_enabled=true, upscale_factor=1.5) with no diffusion repaint. A 1024×1024 request then returns a 1536×1536 PNG.
8. The client polls /api/zimage-check until the job completes, then downloads the image from the S3 URL returned by RunPod.

Generation Flow — FLUX.2-klein (RunPod Serverless)

1. User selects FLUX.2-klein model, chooses a quality preset, configures a multi-LoRA stack, and optionally sets seed, prompt length limit, detail refinement, and upscaling options.
2. Tasks are added to the Persistent Queue with the same AI prompt engineering pipeline.
3. Background processor picks the next task:
   • AI synthesizes the prompt using the FLUX Prompt Director — a specialized system prompt tuned for FLUX.2 [klein] 9B (camera/film language, avoids SDXL boilerplate).
4. Job is submitted to the RunPod FLUX.2-klein Serverless endpoint (/run).
5. The client polls /api/zimage-check until the job completes, then downloads the JPEG from the S3 presigned URL returned by RunPod.

Enhance Flow

1. User opens the Enhance tab and selects an engine: fal.ai Phota, RunningHub Enhance, RunningHub Enhance+Detail, or RunningHub HD Detailer.
2. User provides an image (file upload or URL). Any result in the queue can be sent directly via Send to Enhance.
3. For fal.ai Phota: image is submitted to fal-ai/phota/enhance synchronously; result is downloaded and saved.
4. For RunningHub engines: uploaded files are first uploaded to S3 and converted to temporary presigned URLs; public URLs are used directly.
5. The task is submitted to the respective RunningHub app; client polls /api/check for completion and downloads the result.

Video Creation Flow

1. User opens the Create Video tab and writes a prompt.
2. Optionally adds up to 9 reference images, up to 3 reference videos, and up to 3 reference audio files (paste URL or upload from device). Any image result in the queue can be sent directly via Send to Video.
3. User configures resolution (480p/720p/1080p), duration, aspect ratio, audio generation, optional seed, and optional end-user ID.
4. Clicking Add Video to Queue submits the task to the queue.
5. The UI and server validate Seedance constraints before fal.ai submit: prompt required, max 9 images, max 3 video references, max 3 audio references, max 12 total references, supported file types, supported enum values, and reference audio requiring at least one image or video reference.
6. Background processor submits to POST https://queue.fal.run/bytedance/seedance-2.0/reference-to-video.
7. Client polls /api/video-check every 5 seconds. When complete, the mp4 is downloaded and saved to the output volume.

Upscale Flow

1. User uploads images via the Upscale tab.
2. Background processor picks the next upscale task:
   • If TT-Decoder toggle is ON: The image is encoded into a new carrier PNG using TT-Encoder.
   • The image (original or encoded) is uploaded to S3 storage.
   • A temporary presigned URL is generated and sent to the selected RunningHub upscale workflow:
     • RunningHub — 2K Upscale uses the existing 2K workflow, switching to the TT carrier workflow when TT-Decoder is enabled.
     • RunningHub — API Upscale submits to RunningHub app 2053348161841836033 with node 125.
3. The client polls status and downloads the upscaled result.

Quick Start

Prerequisites

• Docker & Docker Compose
• A Google Gemini API key or a RunPod API key
• A RunningHub API key (required for FLUX.1-dev, Upscaling, and RunningHub Enhance)
• A RunPod API key (required for Z-Image, FLUX.2-klein, and Qwen prompt provider)
• A fal.ai API key (required for Enhance via Phota and Create Video)
• S3-compatible Storage (Required for Upscaling and RunningHub Enhance file uploads) — e.g., Backblaze B2.

Run with Docker (Recommended)

# Clone the repository
git clone <repo-url>
cd rhub

# Configure environment variables
cp .env.example .env
# Edit .env with your API keys, S3 credentials, and RunPod endpoints

# Ensure the shared Docker network exists
docker network create shared_net 2>/dev/null || true

# Build and start
docker compose up -d --build

The container is intended to be reached through NPM Proxy Manager on the shared Docker network. It does not expose the application port directly to the local host, so use the configured proxy hostname for browser access rather than localhost:3000.

Configuration

API keys can be set in .env (recommended for persistent use) or entered directly in the Web UI. UI values override .env values.

Environment Variables

Web UI Settings

Generation Parameters

Shared (all models)

Z-Image (RunPod Serverless)

FLUX.2-klein (RunPod Serverless)

Create Video (fal.ai Seedance 2.0)

Create Video validation is enforced before fal.ai submission. Reference images must be JPEG/PNG/WebP and no more than 30MB each. Reference videos must be MP4/MOV and uploaded video data URIs are limited to 50MB total. Reference audio must be MP3/WAV and no more than 15MB each. fal.ai accepts public http(s) URLs or base64 data URIs for file inputs. The Seedance request can include no references at all, image references, video references, audio references with at least one image/video reference, or any supported combination within the 12-file total limit.

API Reference

POST /api/generate

Submits an image generation job. Handles AI prompt engineering via Gemini or RunPod Qwen, then routes to the selected model backend.

• FLUX.1-dev: Submits to RunningHub workflow. Returns { taskId, model: 'flux-dev', prompt }.
• Z-Image: Submits to RunPod Z-Image Serverless endpoint with multi-LoRA loras array, Base-model defaults (steps=50, shift=1.0, cfg_normalization=true), selectable upscale_model, default img2img hires-fix controls, and fallback single-pass detail upscale controls. Returns { jobId, model: 'z-image', prompt }.
• FLUX.2-klein: Submits to RunPod FLUX.2-klein Serverless endpoint with preset, explicit width/height from the selected aspect ratio, multi-LoRA loras, lora_scale_mode, max_sequence_length, optional 2nd pass options, and optional upscale options. Returns { jobId, model: 'flux-klein', prompt }.

POST /api/zimage-check

Polls a RunPod job (Z-Image or FLUX.2-klein) for completion. When the job completes, downloads the image from the S3 presigned URL and saves it to the output directory. Returns { status, filename }.

POST /api/upscale

Handles multipart form uploads. Encodes images if requested, uploads to S3, and submits to the selected RunningHub upscaling workflow. upscaleEngine may be runninghub-2k or runninghub-api.

• runninghub-2k submits to the existing 2K workflow (2022348592370950145) or the TT carrier workflow (2022423075609907202) when useTtDecoder=true.
• runninghub-api submits to app 2053348161841836033 with nodeInfoList[0].nodeId = "125" and the uploaded image presigned URL as fieldValue.

POST /api/check

Polls RunningHub task status and handles post-processing (image download + optional TT-Decode).

POST /api/enhance

Handles image enhancement. Accepts multipart form with engine (fal, runninghub, runninghub-detail, runninghub-hd-detail), image file or URL. For fal.ai Phota: runs synchronously and returns { filename }. For RunningHub engines: uploads files to S3 for a temporary presigned URL when needed, submits the URL to RunningHub, and returns { taskId } for polling.

POST /api/video

Submits a video generation job to the fal.ai queue (bytedance/seedance-2.0/reference-to-video). Supports the fal.ai input surface: prompt, image_urls, video_urls, audio_urls, resolution, duration, aspect_ratio, generate_audio, seed, and end_user_id. Validates prompt, enum values, reference counts, URL/data URI shape, MIME types, uploaded data URI size limits, and the fal.ai rule that reference audio requires an image/video reference. Returns { requestId, statusUrl, responseUrl, outputDir, prefix }.

POST /api/video-check

Polls a fal.ai video job for completion. When complete, downloads the mp4 and saves it to the output directory. Returns { status, filename }.

GET /api/images/[...path]

Serves generated/upscaled/enhanced images and videos from the mounted output volume.

Project Structure

rhub/
├── src/
│   ├── lib/
│   │   ├── loras-klein.json          # FLUX.2-klein LoRA preset list (generated by generate-loras.sh)
│   │   ├── loras-zimage.json         # Z-Image LoRA preset list (generated by generate-loras.sh)
│   │   ├── tt-decoder.ts             # LSB Steganography extraction
│   │   ├── tt-encoder.ts             # LSB Steganography embedding
│   │   ├── s3.ts                     # S3 Client & Presigned URL logic
│   │   └── locations.ts              # 300 photogenic locations
│   └── routes/
│       ├── +page.svelte              # Main UI (Runes) — Generate, Upscale, Enhance & Create Video tabs
│       ├── +page.server.ts           # Server load — passes env-backed API keys + LoRA lists to UI
│       └── api/
│           ├── generate/             # AI Synthesis + Multi-model Submission
│           ├── zimage-check/         # RunPod job polling + image download (Z-Image & FLUX.2-klein)
│           ├── upscale/              # Upload + Encoding + S3 Hosting
│           ├── check/                # RunningHub task polling + TT-Decode
│           ├── enhance/              # Image enhancement (fal.ai Phota / RunningHub workflows)
│           ├── video/                # fal.ai Seedance 2.0 video submission
│           ├── video-check/          # fal.ai video job polling + mp4 download
│           └── images/               # Static file serving from /mount
├── generate-loras.sh                 # Host script — regenerates LoRA JSON configs from local dirs
├── .env.example                      # Template for secrets and limits
├── .env                              # Local secrets (gitignored)
├── Dockerfile                        # Production build
└── docker-compose.yml                # Container orchestration

Updating the LoRA Presets

Run the host-side script before rebuilding the container whenever LoRA files are added or removed:

bash generate-loras.sh
docker compose up -d --build

The script scans:

• /mnt/backblaze/storage/LoRA/Civitai/flux.2-klein-9b/ → src/lib/loras-klein.json
• /mnt/backblaze/storage/LoRA/Civitai/zImage/ → src/lib/loras-zimage.json

Tech Stack

• Frontend: Svelte 5 (Runes), TypeScript, SvelteKit
• Backend: Node.js, AWS SDK (S3), pngjs
• AI: Gemini 3 Flash / RunPod Qwen 30B
• Image Generation: FLUX.1-dev (RunningHub) / Z-Image (RunPod Serverless) / FLUX.2-klein (RunPod Serverless)
• Image Enhancement: fal.ai Phota / RunningHub Enhance workflows
• Video Generation: fal.ai Seedance 2.0 (bytedance/seedance-2.0/reference-to-video)
• Infrastructure: Docker, Docker Compose

License

Private — All rights reserved.