rhub — RunningHub Precision Control Center

Advanced image 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, image upscaling with LSB steganography support, and real-time polling.

rhub is a specialized SvelteKit-based dashboard that transforms simple subject descriptions into high-quality, LoRA-consistent imagery. 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.
• 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 to 2K resolution using specialized RunningHub workflows. Handles intermediary storage via S3 (e.g., Backblaze B2) with automatic presigned URL generation.
• 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 — Segmented control interface with smooth sliding indicators for seamless switching between Generation and Upscaling modes.
• 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.

Architecture

The application runs as a single SvelteKit container. API routes handle server-side logic including AI prompt synthesis, S3 uploads, RunningHub interaction, and direct RunPod Serverless calls. Images 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 new multi-LoRA loras array.
5. The client polls /api/zimage-check until the job completes, then downloads the JPG from the S3 URL returned by RunPod.
6. Optionally, a High-Res Refinement second pass is run server-side before delivery.

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.

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 RunningHub 2K Upscale workflow.
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 and Upscaling)
• A RunPod API key (required for Z-Image, FLUX.2-klein, and Qwen prompt provider)
• S3-compatible Storage (Required for Upscaling) — 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

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)

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. 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 specialized RunningHub upscaling workflows.

POST /api/check

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

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

Serves generated/upscaled images 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 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
│           └── 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)
• Infrastructure: Docker, Docker Compose

License

Private — All rights reserved.