A modular, local-first AI image generation engine — built to be forked, extended, and owned.

I.R.I.S. is an open-source AI image generation platform designed as a foundation, not a locked product.
Think of it as Linux for AI image generation:

You get a fully working system —
but you decide how it evolves.

⚠️ Runs entirely on your own hardware
No cloud. No accounts. No telemetry. No vendor lock-in.

• 🧠 Local-first — everything runs on your machine
• 🔓 Open Source — modify, fork, redistribute
• 🧩 Modular architecture — UI, backend, models are replaceable
• 🧪 Experiment-friendly — designed for tinkering & research
• 🚀 Production-capable — APIs, WebSockets, scaling-ready

This repository provides a fully functional reference implementation, not a closed product.

• Modern React Frontend — Responsive UI built with React 18 & Tailwind CSS
• Plugin System — Install, manage, and use custom AI models via ZIP packages
• Advanced Image Upscaler — AI-powered upscaling from 2x to 16x with multiple models
• Local Model Management — Load models from local directories (HuggingFace Hub format)
• Multiple AI models (anime, realistic, pixel art, SDXL)
• Text-to-Image generation with real-time progress
• WebSocket streaming for live updates
• Persistent prompt history (server-side)
• Multi-GPU support (NVIDIA CUDA, AMD ROCm, Intel Arc XPU, Apple MPS, CPU)

• DRAM Extension — System RAM fallback for low VRAM GPUs (4GB+)
• Multiple Upscalers — Real-ESRGAN, Anime v3, Tile Mode, Lanczos
• Custom resolutions (256×256 → 2048×2048)
• Hardware monitoring — CPU, RAM, GPU power draw
• Device switching — Switch between GPU/CPU at runtime
• Discord bot integration — Auto-post generated images
• Discord Rich Presence — Show generation status

• Python 3.9 – 3.11
• GPU recommended (4 GB VRAM minimum)
• CUDA 11.8+ / ROCm 5.6+ / oneAPI (optional, CPU mode supported)

git clone https://github.com/KaiTooast/iris.git
cd iris

python -m venv venv
# Windows
venv\Scripts\activate
# Linux / macOS
source venv/bin/activate

pip install -r requirements.txt

# Build React frontend
build_frontend.bat  # Windows
# or manually: cd frontend && npm install && npm run build

# Optional: Copy environment template
cp .env.example .env

# Windows (use venv python directly)
.\venv\Scripts\python.exe src/start.py

# Linux / macOS
python src/start.py

# Server Modes
python src/start.py                 # React frontend (default)
python src/start.py --mode react    # React frontend (explicit)
python src/start.py --mode api      # API only (no frontend)

# Without Discord bot
python src/start.py --no-bot

🌐 Frontend: http://localhost:8000
🔍 Upscaler: http://localhost:8000/upscaler
🔐 Admin Panel: http://localhost:8000/admin

iris/
├── src/                    # Backend & core logic
│   ├── api/                # FastAPI server & routes
│   │   ├── server.py       # Main server (generation, upscaling, settings)
│   │   ├── middleware/     # Rate limiting
│   │   ├── routes/         # API endpoints (system, devices)
│   │   └── services/       # NSFW filter, pipeline, history, queue
│   ├── core/               # Model loading & generation
│   ├── services/           # Discord bot
│   ├── utils/              # Logging, file management
│   └── start.py            # Entry point
│
├── frontend/               # Modern React Web UI
│   ├── src/
│   │   ├── pages/          # HomePage, GeneratePage, GalleryPage, SettingsPage
│   │   ├── components/     # Reusable components
│   │   ├── store/          # Zustand state management
│   │   └── lib/            # API utilities
│   ├── package.json
│   └── vite.config.js
│
├── static/                 # Static assets & runtime data
│   ├── css/                # Stylesheets
│   ├── js/                 # JavaScript
│   ├── config/             # Bot config files
│   └── data/               # History (prompts_history.json)
│
├── assets/                 # Static assets (thumbnails, icons)
│   └── thumbnails/         # Model thumbnails (WebP)
│
├── outputs/                # Generated images
├── Logs/                   # Runtime logs
├── docs/                   # Documentation
│
├── settings.json           # Runtime settings
└── requirements.txt        # Python dependencies

{
  "dramEnabled": true,
  "vramThreshold": 6,
  "maxDram": 16,
  "discordEnabled": false
}

HOST=0.0.0.0
PORT=8000
DEFAULT_MODEL=anime_kawai

# Discord Bot (optional)
DISCORD_BOT_TOKEN=your_token
DISCORD_CHANNEL_NEW_IMAGES=channel_id
DISCORD_CHANNEL_VARIATIONS=channel_id
DISCORD_CHANNEL_UPSCALED=channel_id

💡 AMD GPU Note: RDNA3+ GPUs (RX 7000/9000 series) include dedicated Matrix Cores for AI workloads, providing significant performance improvements over RDNA1/2. RDNA4 (RX 9000 series) features enhanced AI accelerators specifically optimized for diffusion models.

💡 Developer Note: I.R.I.S. was developed and tested on a GTX 1650, proving functionality on low-end hardware.

I.R.I.S. features a flexible plugin system that allows you to install, manage, and use custom AI models without modifying source code.

Plugins are ZIP packages containing:

• manifest.json — Model metadata and HuggingFace repository reference
• thumbnail.webp — Preview image for the UI

Access the Plugin Manager at http://localhost:8000/plugins

Features:

• 📦 Install plugins via drag-and-drop ZIP upload
• ✅ Enable/disable plugins without uninstalling
• 🗑️ Uninstall plugins with one click
• 📥 Automatic model downloads from HuggingFace
• 🔍 Search and filter by model type, base, or status
• 🖼️ Visual thumbnails for easy identification

1. Create manifest.json:

{
  "name": "My Custom Model",
  "description": "A custom AI model for specific use cases",
  "version": "1.0.0",
  "thumbnail": "thumbnail.webp",
  "hf_repo": "author/model-repo-id",
  "type": "txt2img",
  "base": "sd1.5",
  "recommended_steps": 30,
  "recommended_cfg": 7.5,
  "supports_negative_prompt": true
}

2. Add a thumbnail (512×512 or 768×768 WebP image)

3. Package as ZIP:

zip my-model-plugin.zip manifest.json thumbnail.webp

4. Install via Plugin Manager UI

# List all plugins
GET /api/plugins/list

# Install plugin
POST /api/plugins/install
Content-Type: multipart/form-data
Body: file=plugin.zip

# Enable plugin
POST /api/plugins/enable/{plugin_id}

# Disable plugin
POST /api/plugins/disable/{plugin_id}

# Uninstall plugin
DELETE /api/plugins/uninstall/{plugin_id}

# Get plugin details
GET /api/plugins/{plugin_id}

# WebSocket for download progress
WS /ws/download/{plugin_id}

I.R.I.S. comes with 11 pre-installed plugins:

• Dreamshaper 8 (versatile allround model)
• Anime Kawai Diffusion
• Abyssorangemix3 (semi-realistic anime)
• Counterfeit V3.0 (detailed illustrations)
• Openjourney (artistic style)
• Pixel Art Diffusion
• Anything V5 (classic anime)
• Stable Diffusion 2.1 (realistic photos)
• Waifu Diffusion
• Stable Diffusion 3.5 Medium (AMD GPU optimized)
• Animagine XL 3.1 (high-quality anime SDXL)

📖 View Plugin Development Guide - Complete guide for creating custom plugins.

• REST API for generation, gallery, system info
• WebSocket streams for:
  • Generation progress
  • Model download progress
  • Gallery updates
  • Multi-page synchronization

Perfect for custom frontends, automation, or external clients.

📖 View Full API Documentation - Complete reference for REST endpoints, WebSocket messages, and error handling.

You are explicitly encouraged to:

• Replace the frontend entirely
• Add your own models or pipelines
• Build a token or subscription system
• Deploy in a private or public datacenter
• Run on NVIDIA, AMD, or Intel GPUs (experimental)
• Fork this into a commercial or closed product

I.R.I.S. does not enforce a business model.

Creative Commons Attribution 4.0 (CC BY 4.0)

You may use, modify, redistribute, and commercialize this project — attribution is required.

See LICENSE for details.

Contributions are welcome — from small fixes to major architectural changes.

Please read CONTRIBUTING.md before submitting a pull request.

I.R.I.S. is not built to compete with cloud AI platforms.

It exists to give control back to developers and creators.

If you value:

• ownership over subscriptions
• experimentation over lock-in
• transparency over black boxes

then this project is for you.