haplollc

haplollc / Mirage

Public

One-stop on-device diffusion image-generation engine for iOS / macOS / visionOS. Embeds stable-diffusion.cpp + ggml-metal behind a tight Swift API. Supports SD, SDXL, SD3, Flux, Chroma, Qwen-Image, ERNIE-Image, Z-Image, and anything else sd.cpp can load.

12
0
89% credibility
Found May 22, 2026 at 14 stars -- GitGems finds repos before they trend. Get early access to the next one.
Sign Up Free
AI Analysis
Swift
AI Summary

Mirage is a Swift library that lets app developers add AI image generation directly to iPhone, iPad, and Mac apps. Instead of sending prompts to cloud services, the AI runs entirely on the user's device using Apple's Metal GPU technology. Developers can choose from various AI models (like Z-Image-Turbo, Stable Diffusion, or Flux) and the library handles all the complex GPU programming behind a simple interface. This approach keeps user data private, works offline, and avoids per-request cloud costs. The library is designed for production use with memory management for large models and progress reporting for good user experience.

How It Works

1
💡 You want AI image generation in your app

You discover Mirage and realize you can add powerful AI image creation without sending data to cloud services.

2
📦 You add Mirage to your project

With a few clicks in Xcode, Mirage becomes part of your app just like any other library.

3
🤖 You download an AI model

You pick a model like Z-Image-Turbo and download it to your app's storage—the same way you'd download any large file.

4
✨ You create your image generator

You write a few lines of code to connect your model files, and Mirage sets everything up to run on your user's device.

5
🎨 You type a prompt and generate

Your user enters something like 'a golden retriever puppy in wildflowers' and taps generate—the AI creates the image right on their phone.

6
📱 Progress shows while it works

Your app displays 'Step 3 of 9' while the image builds, so users know something exciting is happening.

🖼️ Your user gets their AI image

A beautiful 1024x1024 image appears, created entirely on-device—private, fast, and working even without internet.

Sign up to see the full architecture

5 more

Sign Up Free

Star Growth

See how this repo grew from 14 to 12 stars Sign Up Free
Repurpose This Repo

Repurpose is a Pro feature

Generate ready-to-use prompts for X threads, LinkedIn posts, blog posts, YouTube scripts, and more -- with full repo context baked in.

Unlock Repurpose
AI-Generated Review

What is Mirage?

Mirage is a Swift package that puts image generation directly on iPhones, Macs, and Vision Pro devices. It wraps stable-diffusion.cpp and Metal GPU acceleration behind a clean Swift API, letting you generate images from prompts without any cloud dependency. You pass in model files (downloaded from HuggingFace bundles), create an Engine, and await a CGImage. It supports most modern diffusion architectures: SDXL, Flux, SD3, Z-Image-Turbo, ERNIE-Image-Turbo, and anything else the underlying engine can load.

Why is it gaining traction?

The killer feature is that Apple does not need to ship Core ML conversions for every new model. Apple's native library only supports a handful of converted checkpoints; Mirage sidesteps that entirely by running the ggml backend directly. For iOS developers, this means access to newer architectures like Z-Image-Turbo and Flux months before any official Apple support. The prebuilt XCFramework ships as a binary SPM target, so you do not need cmake or ninja to integrate it. Memory tuning is already done: mmap, CPU offloading, and Metal kernel configuration are tuned for iPhone jetsam limits out of the box.

Who should use this?

iOS/macOS app developers building AI-powered creative tools who want image generation that works offline and respects user privacy. Particularly useful if you need newer architectures like Flux or Z-Image-Turbo that Apple has not converted yet. Not suitable for quick prototyping: models run 3-10 minutes on iPhone, and you need to handle multi-GB downloads and memory management yourself. Also avoid if you already ship llama.cpp in the same app without reading the symbol-collision section of the docs first.

Verdict

Mirage solves a real gap in Apple's ecosystem, and the engineering is thorough. However, 12 stars and a 0.9% credibility score signal an early, community-untested project. The documentation is excellent for its age, but you are adopting before the kinks are ironed out. Worth evaluating if on-device diffusion is core to your product; otherwise, wait for wider adoption.

Sign up to read the full AI review Sign Up Free

Similar repos coming soon.