✨ DreamGen

Generate unlimited AI images locally with no subscriptions, no cloud APIs, and complete privacy. Your machine dreams with you! ✨

✨ Modern Web Interface

Beautiful, VS Code-inspired dark theme with real-time generation and organized galleries. The web interface features:

• 🎨 Smart Generation Dashboard - AI-enhanced prompts with contextual plugins
• 🖼️ Weekly Gallery Organization - Browse your creations by week with thumbnail previews
• ⚙️ Plugin Management - Configure time-aware and artistic enhancement plugins
• 📊 Real-time Status - Monitor API, GPU, and generation progress

🚀 Quick Install

# Clone the repository
git clone https://github.com/Agentic-Insights/dreamgen
cd dreamgen

# Install Python dependencies
uv sync

# Configure the app
cp .env.example .env
# Edit .env for your machine:
# - OLLAMA_MODEL must point at a local Ollama model
# - HF_TOKEN is optional for small/turbo/smoke public models
# - IMAGE_BACKEND=auto uses FLUX if cached, otherwise the small public fallback

# Generate from the CLI
uv run dreamgen generate

# Start the API (terminal 1)
uv run uvicorn src.api.server:app --host 127.0.0.1 --port 25800

# Start the web UI (terminal 2)
cd web-ui
npm install
npm run dev

The local dev UI runs at http://localhost:3000 and talks to the API at http://localhost:25800.

For a production-style local run with the shipped ports and wiring:

cp .env.docker.example .env.docker
docker compose --env-file .env.docker up --build

That exposes:

• UI: http://localhost:7860
• API: http://localhost:25800
• API docs: http://localhost:25800/api/docs

🔑 Why Choose This?

• 🏠 100% Local: No cloud APIs, no usage limits, complete privacy
• 🧠 Smart Prompts: AI-enhanced prompts with time, holidays, and art styles
• 🌐 Modern UI: Professional web interface with galleries and real-time updates
• 💰 Zero Cost: Generate unlimited images after initial setup
• 🔌 Extensible: Plugin system for custom prompt enhancements

🎮 Quick Commands

# Generate a single image
uv run dreamgen generate

# Generate with interactive prompt refinement
uv run dreamgen generate --interactive

# Generate multiple images in a batch
uv run dreamgen loop --batch-size 10 --interval 300

# Use mock mode (no GPU required)
uv run dreamgen generate --mock

# Force the local Z-Image backend
uv run dreamgen generate --backend zimage

# List prompt plugins
uv run dreamgen plugins list

# Get help
uv run dreamgen --help

🔧 Requirements

• Python 3.11+ with uv package manager
• Ollama for prompt generation (ollama.ai)
• Hugging Face Token for gated/private model downloads only
• GPU recommended: NVIDIA (8GB+ VRAM) or Apple Silicon

📖 Full Documentation

For detailed setup, Docker usage, and development workflow:

• docs/DOCKER.md
• docs/CONTRIBUTING.md

☁️ Optional: Cloudflare Hosting

DreamGen includes two Cloudflare Workers for free, global image hosting:

1. Single Image Worker (host-image/)

Purpose: Host a single showcase image from R2 storage Use Case: README badges, social media previews, landing pages

Features:

• Serves the most recent PNG from R2
• R2 bucket binding: DREAM_BUCKET → continuous-image-gen
• CORS enabled, 1-day cache
• Simple TypeScript worker

Setup:

cd host-image
npx wrangler deploy

Configuration (wrangler.jsonc):

{
  "name": "host-image",
  "main": "src/index.ts",
  "r2_buckets": [
    { "binding": "DREAM_BUCKET", "bucket_name": "continuous-image-gen" }
  ]
}

2. Gallery API Worker (cloudflare-gallery/)

Purpose: Full gallery API with listing and image retrieval Use Case: Web UI backend, public gallery, API integrations

Features:

• Dynamic routing via Cloudflare Pages Functions ([[path]].js)
• List endpoint: GET /api/images → returns sorted image keys
• Serve endpoint: GET /api/images/{path} → streams image files
• R2 bucket binding: GALLERY → dreamgen-gallery
• Auto-detects content types (png/jpg/webp/gif)
• CORS enabled, 1-year cache for images

Setup:

cd cloudflare-gallery
npx wrangler pages deploy public

Configuration (wrangler.toml):

name = "dreamgen-gallery"
pages_build_output_dir = "public"
[[r2_buckets]]
binding = "GALLERY"
bucket_name = "dreamgen-gallery"

API Endpoints:

# List all images (sorted by upload date, newest first)
curl https://your-worker.pages.dev/api/images

# Get specific image
curl https://your-worker.pages.dev/api/images/2024/week_52/image.png

Key Differences:

Feature	host-image	cloudflare-gallery
Type	Cloudflare Worker	Pages Function
Routing	Single endpoint	Dynamic catch-all
Images	1 hardcoded	Full R2 listing
Cache	1 day	1 year
Use Case	Static showcase	Dynamic gallery API

---

Built by Agentic Insights • Report Issues