Rengu Flow

Preliminary release (v0.4.x) — Rengu Flow is under active development. APIs, config keys, CLI commands, and documentation may change in breaking or non-breaking ways between releases. Pin versions and re-read the docs when upgrading.

A TOML-driven training framework for diffusion models. You describe a run in a config file — model, adapter, optimizer, LR scheduler, dataset, and training options — and Rengu Flow launches it with DeepSpeed. Everything is modular and registry-based: models, adapters, optimizers, and schedulers are selected and configured entirely from TOML, with an optional local web UI on top.

Why Rengu Flow

• Config-first — One main TOML points to a dataset TOML and sets model, adapter, optimizer, scheduler, and training options. No code changes to start a run.
• Modular & registry-based — Models, adapters, optimizers, and schedulers are pluggable; extend the framework by registering new ones (see architecture).
• VRAM-aware — Block swap (CPU offload of transformer blocks), activation checkpointing and offload, optional quantization, gradient release, and OOM-skip let large models train on a single consumer GPU.
• Self-managing dependencies — The rengu CLI drives uv: it creates the venv, installs Python, and pulls only the optional extras a given config needs (e.g. Cosmos deps when [model] type = "cosmos_predict2").
• External control — Drop signal files in the run directory (save, save_quit, export_model, preview_now, …) to checkpoint, export, preview, or exit cleanly — no API or restart required.
• Local web UI — Optional control panel to build configs and datasets, launch and queue runs, send signals, and watch live progress and previews.

Features

• Adapters & full finetune — LoRA, LoKr (vendored, ComfyUI/Forge-compatible saves), the full LyCORIS algorithm family, and adapter-free full-model finetuning.
• Datasets — Directory datasets with aspect-ratio buckets, multi-resolution resolution schedules, a disk cache (v2) for latents and text embeddings, tag dropout / caption variants, and opt-in augmentation presets.
• Dataset Studio (rengu prep) — Auto-tagging, captioning, watermark cleanup, and a bulk tag editor for preparing training data (guide).
• Training loop — Periodic evaluation on held-out datasets, image previews during training, min-SNR / debiased loss weighting, EMA, and torch.compile.
• Checkpointing & export — Resume checkpoints vs. inference exports, retention limits, scheduled saves, and optional async export (guide).
• Experiment tracking — A single sink fans out to a local manifest, TensorBoard, and (opt-in) Weights & Biases.
• Optimizers & schedulers — Built-in names, fully-qualified import paths, and vendored/extended optimizers (e.g. Prodigy, Automagic, K-Optimizers) selected from TOML.

Supported models and adapters

Adapter selection. Set [adapter] type = "lora" / "lokr" / a lycoris_* type; omit [adapter] entirely for full-model finetune. The LyCORIS family (requires the lycoris extra) covers: lycoris_locon, lycoris_loha, lycoris_lokr, lycoris_dylora, lycoris_glora, lycoris_diag_oft, lycoris_boft (DoRA is the dora_wd toggle on locon/loha/lokr, not a separate type). See SDXL training, Cosmos Predict2 / Anima, and full-model finetuning.

Requirements

You install these (system level):

• OS — Linux/WSL2 (multi-GPU, the deepspeed engine) or native Windows (single-GPU, the accelerate engine — no DeepSpeed required). See the native Windows install guide and the WSL workflow.
• NVIDIA GPU + driver — a CUDA-capable GPU with a driver recent enough for CUDA 13.x (check the "CUDA Version" reported by nvidia-smi). Download: NVIDIA drivers.
• CUDA Toolkit 13.x — provides nvcc, which DeepSpeed uses to JIT-compile its C++/CUDA ops on the deepspeed engine (Linux/WSL). Its major version must match the PyTorch build (CUDA 13). The native-Windows accelerate engine does not use DeepSpeed, so nvcc is optional there (only torch.compile benefits from a toolchain). Point CUDA_HOME at the toolkit if it is not auto-detected. Download: CUDA Toolkit 13.x.
• uv — required on PATH for ./rengu (and rengu.cmd on Windows). uv creates .venv and installs a compatible Python (3.10–3.13) automatically; no separate system python3 needed. Install: uv.
• (native Windows, optional) Visual Studio Build Tools — only needed if you use torch.compile. Download: VS Build Tools (select "Desktop development with C++").
• (web UI, optional) Node.js + pnpm — only needed to build the web UI frontend (rengu ui / rengu ui build); the API itself is pure Python. The frontend uses Vite 8, which requires Node.js ≥ 20.19 or ≥ 22.12 — the 22 LTS line is recommended (older Node, e.g. 18, fails the build). Builds prefer pnpm (npm is used as a fallback). With Volta, set it per project: volta pin node@22 pnpm. Download: Node.js.

Installed automatically (by rengu init / uv sync):

• PyTorch 2.12 + CUDA 13.0 (torch==2.12.0+cu130), torchvision 0.27, and DeepSpeed 0.19, from the PyTorch cu130 index.
• The CUDA 13 runtime stack — cuDNN, cuBLAS, NCCL, cuFFT, cuRAND, … — ships inside those PyTorch wheels (as nvidia-*-cu13 packages). You do not install cuDNN or the runtime libraries separately.
• All remaining Python deps (diffusers, PEFT, safetensors, …). Exact versions are pinned in pyproject.toml and uv.lock.

Tested stack (May 2026, WSL2 + NVIDIA): Python 3.13, torch 2.12.0+cu130, torchvision 0.27.0+cu130, deepspeed 0.19.0 — verified end-to-end on an 8 GB RTX 3000 Ada (SDXL + Cosmos LoRA and SDXL full-finetune smokes).

Installation

From the repository root (Linux):

./rengu init          # create rengu.local.toml + uv sync (base training stack)
./rengu init ui       # also install the web UI extra

The ./rengu wrapper runs uv sync on first use, so the venv is built automatically. Install optional extras by listing profiles:

./rengu init cosmos lycoris   # Cosmos Predict2 + LyCORIS adapters
./rengu init all              # every documented extra

./rengu init --only-config writes rengu.local.toml and directories without syncing. Advanced users can run uv sync themselves and call .venv/bin/rengu directly. Before any train/validate/cache (and prep/ui), Rengu Flow inspects what it needs and auto-installs any missing extras — additively, leaving your other profiles in place.

Adding a profile later? Use ./rengu init <profile> or ./rengu update (both additive). A bare uv sync --extra <x> is an exact sync: it installs that extra but removes any you don't list — e.g. uv sync --extra prep after a UI install drops the ui extra (uvicorn) and the UI stops serving. Re-list every extra you want, or just let the on-demand installer handle it.

Updating

./rengu update          # stable channel: fast-forward main, re-sync, rebuild UI if present
./rengu update --beta   # beta channel: switch to the develop branch and update it

rengu update pulls the latest project code, re-syncs dependencies from the lockfile, and recompiles the web UI if it was built locally. It also refreshes the optional profiles you already installed (so git-pinned extras like kaon move to their new commit pin); profiles you never installed are left alone.

Release channels. rengu update tracks main (stable); rengu update --beta switches the checkout to the develop branch (beta) and updates it. Switching back is just rengu update. While on the beta channel, rengu version and the web UI show a beta marker — the channel is derived from the git branch, not the version number. Useful flags: --all-extras (every documented extra), --no-pull (skip the git pull), and --force (discard local tracked code changes and hard-reset when a fast-forward is blocked — never touches untracked/ignored files, so your UI data dir and jobs.db are safe). Check your version with ./rengu version.

Quick start

1. Set up the environment:

   ./rengu init
   

2. Local settings (optional). rengu init creates rengu.local.toml (gitignored) for machine settings — UI host/port, default GPU count, master port, and subprocess env vars. Model checkpoint paths go in the training TOML, not here. See rengu.local.toml.example.

3. Create a training config from an example:

   cp examples/minimal_config_lora_sdxl.toml my_train.toml
   

   Edit my_train.toml: set the dataset path and [model] paths (e.g. checkpoint_path for SDXL).

4. Train:

   ./rengu train --config my_train.toml
   

   • Validate without training: ./rengu validate --config my_train.toml
   • Build the dataset cache only: ./rengu cache --config my_train.toml
   • Resume from the latest checkpoint: ./rengu train --config my_train.toml --resume-from-checkpoint
   • Run DeepSpeed directly: deepspeed --num_gpus=1 -m rengu_flow.main --config my_train.toml

See the CLI guide for every command, flag, and rengu.local.toml key.

Command-line interface

Trailing args after -- are forwarded to the trainer (e.g. ./rengu train --config my.toml -- --regenerate_cache). Full flag reference: CLI guide.

Web UI

./rengu ui start

Builds the frontend if needed, serves the API, and opens a browser. The UI lets you edit training configs and datasets, launch and queue runs, send signal files, and watch live progress and previews. Live progress is parsed from the job's stdout — no extra config required. See the Web UI user guide.

Controlling a run

Training reacts to signal files dropped in the run directory (also exposed as buttons in the UI):

Details and the full list: signal files.

Documentation

• User guide — Training each model, dataset config and prep, optimizers, previews, checkpoints, signal files, the CLI, and the web UI. Start at the docs index.
• Developer guide — Architecture, the model pipeline contract, adding optimizers/schedulers, networks/adapters, VRAM optimization, and testing.
• Implementation backlog — Planned / deferred work.

Status and known limitations

Rengu Flow is a preliminary release under active development; treat config keys and CLI flags as subject to change between versions. A few specific notes:

• Native Windows is single-GPU only. It runs on the accelerate engine (plain PyTorch, no DeepSpeed). Multi-GPU, optimizer.gradient_release, blocks_to_swap, and pipeline_stages > 1 require the deepspeed engine and are Linux/WSL2 only (they patch DeepSpeed's pipeline engine; Windows has no NCCL). Everything else — caching, gradient accumulation, per-resolution micro-batches, resolution schedules, activation_offload, activation_checkpointing, torch.compile, EMA, eval/previews — works on both. See the native Windows install guide. On WSL2, do not set PYTORCH_CUDA_ALLOC_CONF = "expandable_segments:True" — Rengu Flow detects WSL and applies safe defaults automatically (see the CLI guide).
• Built-in models are SDXL and Cosmos Predict2 / Anima. Other architectures (e.g. Flux) are not yet registered — see backlog.
• Cosmos load_and_fuse_adapter is intentionally unsupported; load adapter weights instead.

Third-party components

Rengu Flow incorporates and adapts work from several projects. See THIRD_PARTY_NOTICES.md for full notices and licenses:

• diffusion-pipe (GPL-3.0) — design and portions of the training flow; vendored optimizers under rengu_flow/vendor/diffusion_pipe_optimizers/.
• NVIDIA Cosmos Predict2 (Apache-2.0) — DiT and LLM-adapter modeling code.
• Alibaba Wan VAE — used by the Cosmos pipeline.
• AI Toolkit / Ostris (MIT) — the Automagic optimizer.

License

Rengu Flow is distributed under the GNU General Public License v3.0 or later (LICENSE). See THIRD_PARTY_NOTICES.md for incorporated components and their licenses.