A local Forge companion that builds structured prompt batches, runs them overnight, manages metadata-based upscales, and watches the boring parts, so your PC can do the babysitting for once.
GitHub Link: https://github.com/Bluenochian/Nightrun
Nightrun is a portable workflow system for Stable Diffusion Forge / Forge-Neo.
It is not a model.
It is not a LoRA.
It is not just another random prompt file.
It is the thing that sits beside Forge and turns a messy local generation setup into something that can actually run for hours without you constantly checking if the prompt broke, the LoRA name was wrong, the GPU is cooking itself, or the whole batch slowly turned into repetitive garbage.
Nightrun is built for long local runs, editable prompt pools, metadata replay, LoRA-aware batching, upscale workflows, cooldown logic, and controlled randomness.
The goal is simple:
Set the run. Leave it alone. Come back to something organized, replayable, and worth sorting through.
---
# ✨ What Nightrun does
Nightrun builds prompts from editable pools, sends jobs through Forge, writes replayable metadata, manages upscales, scans LoRAs, protects long runs with cooldown logic, and keeps the whole thing configurable.
It is made for people who want big batches without babysitting every prompt, every upscale, every progress bar, and every tiny local setup problem.
Main idea:
Controlled chaos, not prompt soup.
---
# 🌙 Main features
## 🧩 Editable prompt pools
Nightrun uses plain .txt prompt pools instead of one giant hardcoded prompt.
You can edit the behavior of the whole machine by changing files like:
- concept
- genre
- abstract_idea
- character
- creature_and_nonhuman
- hair
- eyes
- clothing
- pose
- body_pose
- safe_pose
- glamour_pose
- expression
- sensual_layer
- body_focus
- stocking_layer
- equipment
- environment
- environment_rich
- time_and_weather
- lighting
- camera
- scene_depth
- scene_embellishment
- magic_element
- aura_style
- effects
- style_layer
- effect_layer
- artist_direction
- color_grade
- composition
- quality_style
- detail
- negative_extra
These are the normal engine of Nightrun.
The world module system is deeper and optional. The pool system is where most users should start.
---
## 🎲 Controlled randomness
Nightrun is random, but it is not stupid-random.
You can configure:
- pool chances
- how many items each pool can pick
- boosted chances when related pools appear
- base step ranges
- LoRA chances
- LoRA weight ranges
- maximum random LoRAs
- maximum total LoRAs
- world module chance
- fusion mode chance
- risky pool behavior
- cooldown timing
- upscale behavior
- selection memory penalties
- color repetition penalties
So the run can feel alive without turning into chaos soup.
You are not stuck with one fixed behavior. You can tune the machine until it behaves like your machine.
---
## 🧠 Selection memory
During a run, Nightrun remembers recent choices and penalizes repetition.
That means it can push away from using the same colors, same pool entries, and same prompt patterns too often.
It can track broad color families like:
- blue
- cyan / teal
- red
- purple
- green
- gold
- black
- silver
- iridescent
So if a batch starts drifting too hard into one color mood, Nightrun can push it away.
This is one of the reasons long runs do not feel as repetitive.
---
## 👁️ Rare detail control
Some details are cool only when they stay rare.
For example, heterochromia can be controlled so it does not suddenly take over the whole batch.
Because special eyes stop feeling special when every third image has them.
---
# 🧬 LoRA handling
Nightrun does not just slap LoRAs into the prompt and pray.
It can:
- scan local LoRA folders
- resolve names
- use aliases
- soft-match ugly filenames
- skip missing LoRAs safely
- randomize LoRA weights
- add synergy/support LoRAs
- cap random LoRAs
- cap total LoRAs
- deduplicate final LoRA tags
This matters because local LoRA libraries are messy.
Sometimes the Civitai name, trigger name, and local filename are all slightly different because apparently peace was never an option.
Nightrun tries to survive that.
---
## 🧪 LoRA safety
Nightrun can skip missing LoRAs instead of crashing the whole run.
It can also limit how many random LoRAs appear and how many total LoRAs can stack.
That means the prompt does not become a cursed pile of everything at once.
---
## 🧬 LoRA synergies
If a trigger LoRA is selected, Nightrun can add matching support LoRAs with controlled chances and weights.
So instead of all LoRAs being isolated random events, some can behave like small connected systems.
---
# 🧠 Coherent world modules
The world module system is optional.
The normal prompt pools are the everyday engine.
The world module system is the coherence layer.
When it activates, Nightrun selects a world/franchise module from franchise_catalog.py and can pull related pieces from the same source family.
That helps the prompt stay internally consistent instead of mixing ten unrelated aesthetics into one broken image.
World modules can include:
- character archetypes
- outfits
- environments
- props and equipment
- factions
- technology
- magic systems
- landscapes
- architecture
- creatures
- ships
- droids
- lighting mood
- color palettes
- cinematic language
- prompt modifiers
The point is not to replace the normal pools.
The point is to give the run a coherent themed spine when that system activates.
---
## 🎭 Fusion mode
Coherence is good.
But sometimes you want controlled madness.
Fusion mode lets Nightrun allow stranger cross-world combinations while reducing risky generic pool chances.
So you can still get unusual mixes, but the machine is not blindly dumping everything into the same prompt like a raccoon in a keyboard factory.
---
# 🔥 Long-run safety
Nightrun is made for long runs, so it includes systems that care about the machine too.
## GPU temperature pause
Nightrun can watch GPU temperature through nvidia-smi.
If the GPU gets too hot, it pauses.
When the GPU cools below the configured resume temperature, it continues.
That means the run can protect itself instead of mindlessly hammering the card all night.
---
## 🧊 VRAM chill sessions
For big batches, Nightrun can schedule random cooldown sessions every now and then.
Example flow:
- run several generations
- pause for a few minutes
- let the system settle
- continue the batch
It is a small thing, but for overnight workflows it matters.
Nightrun is not just “go fast.”
It is “keep going safely.”
---
## 💤 Between-image rest
You can also configure sleep time between images.
So even outside big cooldown sessions, the machine does not have to be tortured nonstop like it owes you money.
---
# 🚀 Upscale workflow
Nightrun supports both scheduled upscale workflows and metadata-based re-upscaling.
It can:
- generate base images
- upscale during full runs
- auto-upscale low-step base renders
- drag and drop metadata into the upscaler
- recreate from metadata if needed
- write new metadata beside upscaled images
- chain later upscales from previous upscale metadata
This matters because a fast base image does not have to stay a rough base image.
If the base render used low steps, Nightrun can still send it through upscale logic and recover quality without wasting time on every single base generation.
---
## 🎲 Randomized base steps
Nightrun can randomly choose base steps between the configured minimum and maximum.
That means not every image has to use the exact same render cost.
Some images can be faster.
Some can be heavier.
The batch gets more natural variation.
---
## 🚀 Low-step auto-upscale
If a base render lands under the configured step threshold, Nightrun can automatically send it through the upscale path.
So a faster hybrid run does not automatically mean throwaway previews.
You can save time on base generations and still get usable final images through upscale logic.
---
# 🪄 Metadata replay
Every image can get a metadata sidecar with the important pieces saved.
That can include:
- seed
- prompt
- negative prompt
- selected pools
- selected modules
- LoRAs
- LoRA sources
- base steps
- status
- upscale reason
- errors
- GPU info when available
So later, you are not staring at a good image wondering:
What the hell made this?
The answer is saved beside it.
---
# 🧪 Validation and dry-run modes
Before wasting GPU time, Nightrun can test itself.
## Validation mode
Checks things like:
- pool loading
- prompt formatting
- LoRA resolution
- missing resources
- alias behavior
- generation logic
## Dry-run mode
Writes prompt and metadata without calling Forge image generation.
So you can see what the run would do before committing to a real batch.
Basically:
Measure twice, render once.
---
# 📊 Prompt variety analyzer
Nightrun includes a tool for checking old metadata and finding patterns.
It can report things like:
- repeated categories
- repeated colors
- repeated modules
- repeated prompt fragments
- world module usage
- exact prompt repeats
- signs that a batch is becoming too samey
This helps tune the machine instead of guessing.
---
# 🖥️ First-run setup
The setup script helps create a local configuration for your machine.
It can:
- ask for your Forge / Forge-Neo path
- ask for output folder
- detect VRAM profile
- check checkpoint path
- count local LoRAs
- check for Ultimate SD Upscale
- create config.local.json
- create setup diagnostics
- create desktop shortcuts
The shared config.json stays portable.
Your private machine paths stay in config.local.json.
That means the project can be shared without leaking your local folder structure.
---
# 🧯 Clean stop signal
Nightrun can stop cleanly after the current image.
No killing the terminal.
No murdering Forge mid-generation.
No half-dead run folder full of sadness.
You hit the stop signal launcher, and Nightrun exits after the current image is done.
---
# 🧭 Included launchers
Nightrun includes Windows launchers for common workflows:
- Run First Setup.bat
- Run Validation Stress Test.bat
- Run One DRY TEST.bat
- Run Nightrun BASE only.bat
- Run Nightrun FULL upscale.bat
- Run 2x Upscale From Metadata.bat
- Run Prompt Variety Analyzer.bat
- Stop After Current Image.bat
- Clear Stop Signal.bat
The idea is to make normal use easy without hiding the deeper config from people who want to tune everything.
---
# ⚙️ What you can configure
A lot.
Nightrun can be tuned through config sections for:
- image count
- checkpoint
- VAE
- Forge preset
- CLIP skip
- positive prompt prefix/suffix
- negative prompt
- base resolution
- base sampler
- base scheduler
- CFG
- random step range
- upscale settings
- low-step auto-upscale threshold
- temperature pause
- cooldown sessions
- sleep between images
- console behavior
- empty run cleanup
- selection memory
- prompt pools
- LoRA pools
- random LoRAs
- LoRA synergies
- LoRA scanning
- world module behavior
- fusion behavior
- maximum LoRA limits
It is meant to be modified.
This is not a locked black box.
It is a machine you can tune.
---
# 📦 Outputs
Runs create organized folders like:
nightrun-YYYYMMDD-HHMMSS
Inside, you may see:
- 0001_base_WIDTHxHEIGHT.png
- 0001_upscale_WIDTHxHEIGHT.png
- 0001_prompt.txt
- 0001_metadata.json
- summary.json
- run.log
- contact_sheet.jpg
- validation_report.json
The exact files depend on the mode you run.
---
# 🛠️ Basic usage
Run setup first:
Run First Setup.bat
Validate before rendering:
Run Validation Stress Test.bat
Preview one prompt without rendering:
Run One DRY TEST.bat
Run base generation:
Run Nightrun BASE only.bat
Run full generation with scheduled upscale:
Run Nightrun FULL upscale.bat
Stop cleanly after the current image:
Stop After Current Image.bat
---
# 🪄 Metadata upscaling
Basic upscale from metadata:
py upscale_from_metadata.py "D:\renders\0001_metadata.json" --config config.local.json --scale 2
Force base image as source:
py upscale_from_metadata.py "D:\renders\0001_metadata.json" --config config.local.json --source base --scale 2
Use an existing upscale as source:
py upscale_from_metadata.py "D:\renders\0001_metadata.json" --config config.local.json --source upscale --scale 2
Dry-run the upscale:
py upscale_from_metadata.py "D:\renders\0001_metadata.json" --config config.local.json --scale 3 --dry-run
---
# ✅ Recommended for
Nightrun is useful if you:
- use Forge / Forge-Neo locally
- generate in large batches
- want overnight runs
- hate babysitting progress bars
- want editable prompt pools
- want safer long-running workflows
- use many LoRAs
- want metadata replay
- want upscaling tied to generation metadata
- want less repetitive outputs
- want a workflow that can be tuned instead of replaced
---
# ⚠️ Notes
Nightrun does not include:
- checkpoints
- LoRA files
- model files
- Forge itself
- Ultimate SD Upscale
- copyrighted assets
You need your own local Forge / Forge-Neo setup and your own models.
Franchise/world module names are used as inspiration labels for prompt organization.
---
# 📝 Release summary
Nightrun is a portable Forge / Forge-Neo workflow system with editable prompt pools, local LoRA scanning, coherent world modules, thermal pause, long-run VRAM chill, randomized base steps, low-step auto-upscale, metadata replay, clean stop control, prompt variety analysis, and drag-and-drop metadata upscaling.
---
🌙 Built for the dark hours between intention and discovery.