Skip to content

Installation

Jump to bottom
The Duskfall Portal Crew edited this page Jun 12, 2026 · 1 revision

Installation Guide

Technical reference for all supported platforms. For the quick-start version, see Getting-Started.

Platform Support

Platform Training Installer Start Script
Windows 10/11 (NVIDIA) Yes install.bat start_services_local.bat
Linux (NVIDIA) Yes install.sh start_services_local.sh
VastAI Yes vastai_setup.sh (auto) Supervisor (auto)
RunPod Yes provision_runpod.sh (auto) start_services_runpod.sh
macOS No training / UI only Manual start_services_local.sh
AMD (ROCm) Community Manual PyTorch ROCm start_services_local.sh

Requirements

Hardware

Component Minimum Recommended
GPU NVIDIA 12 GB VRAM, CUDA 12.1+ NVIDIA 24 GB VRAM
RAM 16 GB 32 GB
Disk 50 GB free 100 GB free

VRAM by model type:

Model Minimum VRAM Notes
SD 1.5 8 GB Small batches
SDXL / Pony / Illustrious / NoobAI 16 GB 24 GB for batch > 1
Flux.1 dev/schnell 24 GB fp8 base helps on 16 GB
Anima 24 GB 40 GB for large batches

Software

Dependency Required Version Notes
Python 3.10 or 3.11 3.12 untested; 3.13 not supported
Node.js 20.19+ 22.x recommended
Git Any recent Needed for clone and updates
CUDA Toolkit 12.1+ Must match PyTorch build
NVIDIA drivers 525.x+ For CUDA 12.1

Installation — Windows

Supported: Windows 10 21H2+ and Windows 11, NVIDIA GPU with CUDA 12.1+.

Install location: Use a path under your user directory (e.g. C:\Users\YourName\Projects\). Avoid C:\, Program Files, OneDrive, Dropbox, Google Drive, network drives — these will cause permission errors.

git clone https://github.com/Ktiseos-Nyx/Ktiseos-Nyx-Trainer.git
cd Ktiseos-Nyx-Trainer
install.bat

Installer flags: --venv, --no-venv, --auto, --no-comfyui, --verbose

The installer creates .venv/, installs PyTorch with CUDA 12.1, Python deps from requirements_windows.txt, and runs npm install && npm run build in frontend/.

Installation — Linux

Supported: Ubuntu 20.04+, Debian 11+, most systemd distros with NVIDIA GPU.

git clone https://github.com/Ktiseos-Nyx/Ktiseos-Nyx-Trainer.git
cd Ktiseos-Nyx-Trainer
chmod +x install.sh
./install.sh

Same flags as Windows. Uses requirements_linux.txt.

Installation — macOS (UI Only)

Training is not supported on macOS (Kohya SS requires CUDA). The web UI and API will run for development.

git clone https://github.com/Ktiseos-Nyx/Ktiseos-Nyx-Trainer.git
cd Ktiseos-Nyx-Trainer
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cd frontend
npm install --legacy-peer-deps
npm run build
cd ..
./start_services_local.sh

Cloud Deployment — VastAI

One-click: Use the deploy button from the README. The template runs vastai_setup.sh automatically on first boot. Recommended spec: RTX 3090 or better, 24 GB+ VRAM, 100 GB disk, Ubuntu 22.04 + CUDA 12.1.

Manual setup:

git clone https://github.com/Ktiseos-Nyx/Ktiseos-Nyx-Trainer.git
cd Ktiseos-Nyx-Trainer
chmod +x vastai_setup.sh
./vastai_setup.sh

vastai_setup.sh deletes package-lock.json (avoids Windows/Linux lockfile mismatch) and uses requirements_cloud.txt to avoid conflicts with the VastAI base image. Services are managed by Supervisor and restart automatically after reboots.

Dev branch:

./vastai_setup_dev.sh

Cloud Deployment — RunPod

One-click: Use the deploy button from the README.

Manual setup:

git clone https://github.com/Ktiseos-Nyx/Ktiseos-Nyx-Trainer.git
cd Ktiseos-Nyx-Trainer
chmod +x provision_runpod.sh
./provision_runpod.sh
./start_services_runpod.sh

Dev branch:

./provision_runpod_dev.sh

Manual / Advanced Setup

Backend (standalone)

# Activate venv
.venv\Scripts\activate          # Windows
source .venv/bin/activate       # Linux

# Start FastAPI
uvicorn api.main:app --host 0.0.0.0 --port 8000

Add --reload for development. Do not use --reload in production.

Frontend (standalone)

cd frontend
npm run dev      # Development (hot reload)
npm run build    # Production build
npm start        # Production server (includes API proxy via server.js)

The npm start command uses server.js which proxies /api/* to the FastAPI backend and handles WebSocket upgrades.

Post-Install: Starting the App

start_services_local.bat    # Windows
./start_services_local.sh   # Linux/macOS
restart.bat                 # Windows quick restart
./restart.sh                # Linux quick restart
./fetch-restart.sh          # Linux: full pull + rebuild + restart

Maintenance Scripts

clean_slate.py

Removes build artifacts without deleting user data. Run when the install is in a broken state that reinstalling hasn't fixed.

python clean_slate.py --dry-run    # Preview only
python clean_slate.py              # Remove .venv, node_modules, .next, caches
python clean_slate.py --nuclear    # Also remove models, datasets, outputs

Preserves: pretrained_model/, vae/, datasets/, output/, presets/, logs/.

diagnose.bat / diagnose.sh

Collects system info for bug reports. Output: diagnostics_YYYYMMDD_HHMMSS.txt.

diagnose.bat      # Windows
./diagnose.sh     # Linux

Collects: OS version, Python/Node/CUDA versions, nvidia-smi, pip/npm packages, recent logs.

Requirements Files Reference

File Used By Contains
requirements_base.txt All platforms Core ML: torch, diffusers, transformers, accelerate, Kohya SS deps
requirements_windows.txt install.bat Base + Windows-specific (bitsandbytes Windows build)
requirements_linux.txt install.sh Base + Linux-specific
requirements_cloud.txt Cloud setup scripts Base + cloud; omits packages pre-installed in cloud images
requirements.txt Manual / macOS Minimal, no PyTorch CUDA

Do not mix platform requirement files — binary builds will fail on the wrong OS.

Environment Variables

Set automatically by installer and start scripts. Documented here for manual setup.

Variable Default Purpose
PYTHONIOENCODING utf-8 Prevents cp1252 errors on Windows
PYTHONUTF8 1 Forces UTF-8 mode
PYTHONUNBUFFERED 1 Disables stdout buffering for real-time logs
NEXT_PUBLIC_API_URL http://localhost:8000/api Backend API base URL
PORT 3000 Frontend port
BACKEND_PORT 8000 FastAPI port

Clone this wiki locally