Skip to content

Getting Started

Jump to bottom
The Duskfall Portal Crew edited this page Mar 3, 2026 · 4 revisions

Getting Started

⚠️ Alpha Status — March 2026
Cross-platform LoRA training interface (Next.js + FastAPI)

This guide walks you through setting up the Ktiseos Nyx Trainer on Windows, Linux, or cloud GPUs.

1. Prerequisites

Core Requirements (All Platforms)

Component Requirement Notes
GPU NVIDIA with CUDA 12.1+ 12GB VRAM minimum, 24GB recommended for SDXL
Python 3.10 or 3.11 Other versions may cause dependency conflicts
Node.js 18+ (LTS recommended) Required for Next.js frontend
Disk Space 50GB+ free For models, datasets, and cache
Git Latest For cloning the repository

Optional (Cloud Deployment)

  • VAST.ai, RunPod, or similar account (only if not running locally)
  • SSH client configured for remote access

2. Installation

Clone the Repository

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

🛡️ Strongly Recommended: Use a Virtual Environment

Isolates dependencies and prevents system-wide conflicts.

Windows

REM Create virtual environment
python -m venv venv

REM Activate it (do this EVERY TIME you open a new terminal)
venv\Scripts\activate

REM Install dependencies
install.bat

Linux / WSL

# Create virtual environment
python3 -m venv venv

# Activate it (do this EVERY TIME you open a new terminal)
source venv/bin/activate

# Install dependencies
./install.sh

💡 Pro Tip: Your terminal prompt will show (venv) when the virtual environment is active. If you don't see it, activate again.

Alternative: Install Without venv (Not Recommended)

If you prefer system-wide installation:

Windows

install.bat

Linux

./install.sh

3. Starting the Application

With Virtual Environment (Recommended)

  1. Activate venv (if not already active):
    • Windows: venv\Scripts\activate
    • Linux: source venv/bin/activate
  2. Start services:
    • Windows: start_services_local.bat
    • Linux: ./start_services_local.sh

Without Virtual Environment

  • Windows: start_services_local.bat
  • Linux: ./start_services_local.sh

Access the Interface

Service URL
Frontend UI http://localhost:3000
Backend API http://localhost:8000
API Documentation http://localhost:8000/docs

4. Deployment Options

Option A: Local Machine

Best for: Development, testing, users with local NVIDIA GPUs.

  • Follow the installation steps above.
  • Ensure CUDA drivers are up to date (nvidia-smi to verify).
  • Run locally via startup scripts.

Option B: Cloud GPU (VAST.ai, RunPod, etc.)

Best for: Users without local GPU hardware.

  1. Rent an Instance: Choose a GPU with sufficient VRAM for your target model.
  2. Deploy:
    • VAST.ai: Use the Deploy on VastAI button in the repo for auto-configured templates.
    • Other Providers: Clone the repo and follow the Linux installation steps.
  3. Expose Ports: Ensure ports 3000 (frontend) and 8000 (backend) are publicly accessible.
  4. Access UI: Navigate to your instance's public IP/URL.

💡 Note: The application is cloud-provider agnostic. VAST.ai is used as an example because it's tested, but any provider supporting Python 3.10+ and Node.js 18+ will work.

5. Your First Training Run

  1. Open the UI: Navigate to http://localhost:3000 (or your cloud instance URL).
  2. Configure Training:
    • Model Path: HuggingFace path (e.g., runwayml/stable-diffusion-v1-5) or local path.
    • Dataset Path: Path to your training data (local or mounted cloud storage).
    • Optimizer: Start with AdamW8bit for stability (see 02-Configuration#Optimizers).
  3. Save Config: Click "Save" to persist settings to localStorage (prevents data loss on refresh).
  4. Start Training: Click "Start Training" and monitor the output panel.
  5. Verify: Check for:
    • ✅ No Pydantic validation errors in the UI
    • ✅ Training logs appearing in real-time
    • ✅ GPU activity via nvidia-smi or cloud monitoring

6. Updating the Application

⚠️ DO NOT delete and re-clone the repository. This creates orphaned cache files and environment shims that cause installation issues.

Proper Update Process

# Navigate to installation directory
cd Ktiseos-Nyx-Trainer

# Pull latest changes
git pull

# Reactivate virtual environment (if using)
venv\Scripts\activate   # Windows
source venv/bin/activate  # Linux

# Update dependencies
install.bat             # Windows
./install.sh            # Linux

💡 The installer scripts are safe to run multiple times and will preserve your datasets, models, and configs.

7. Troubleshooting Installation

If installation fails or the app won't start:

Run the Diagnostic Tool

Collects system info, Python/Node versions, and dependency status.

Windows

diagnose.bat

Linux / WSL

./diagnose.sh

Attach the generated diagnostics_*.txt file to your GitHub Issue.

Common First-Run Checks

  • Virtual environment is activated ((venv) in prompt)
  • CUDA drivers are installed and detected (nvidia-smi)
  • Ports 3000/8000 are not blocked by firewall
  • Python 3.10/3.11 and Node 18+ are in your PATH

8. Next Steps

❓ Need Help?

  1. Check 03-Troubleshooting first.
  2. Review the Support Guidelines.
  3. Open a GitHub Issue with:
    • Your OS and deployment mode (Local/Cloud)
    • Error output / logs
    • The diagnostics_*.txt file if installation failed

Clone this wiki locally