GabrieleLozupone/kokon

The setup screen picks a preset from your VRAM. On a Mac the presets are named by unified memory (16–24 GB Mac, 32–36 GB Mac, 48 GB Mac, 64 GB+ Mac), because the graphics part can use only about two thirds of it and the text encoder shares the same memory. You can change the preset later from Settings → Models → Set up models…

Every preset also gets stable-diffusion.cpp (the CUDA 12 build on NVIDIA, the Vulkan build on AMD and Intel, the Metal build on a Mac), the Qwen-Image 2.1 VAE with madebyollin's texture fix (it removes the faint 2-pixel checkerboard of the original decoder; installs from 0.9.2 or earlier switch to it when you accept the update), the Qwen3-VL vision projector and, on a PC, the Superscale-SP upscaler (67 MB). The image model is Qwen's official 8-step Qwen-Image 2.1 Turbo through DogukanUrker/Qwen-Image-2.1-Turbo-GGUF; the other sources are Qwen/Qwen3-VL-8B-Instruct-GGUF, madebyollin/texture-fix-vae-for-qwen-image-2.1 and Comfy-Org/Qwen-Image-2.1 (the original VAE).

Files go to %LOCALAPPDATA%\KokonData\sdcpp (Mac: ~/Library/Application Support/KokonData/sdcpp) by default. You can point the setup screen at an existing stable-diffusion.cpp folder instead; files that are already there are kept.

Already have Qwen-Image 2.1 files, for example in ComfyUI? Choose Use models I already have in the setup screen and pick the folder (such as ComfyUI\models): Kokon finds the image model, VAE, text encoder and vision projector by their contents, as GGUF or safetensors in any quantization, and downloads only the engine and any piece you don't have. Files stay where they are. Your own files are not tested by Kokon; you can switch to the official files at any time in Settings → Models.

Project-scoped .mcp.json, or any host that takes the standard format (on a Mac the command is /Applications/Kokon.app/Contents/MacOS/kokon-mcp):

{
  "mcpServers": {
    "kokon": {
      "type": "stdio",
      "command": "C:\\Users\\<you>\\AppData\\Local\\Kokon\\kokon-mcp.exe",
      "args": []
    }
  }
}

Same thing from the command line:

claude mcp add-json --scope user kokon '{"type":"stdio","command":"C:\\Users\\<you>\\AppData\\Local\\Kokon\\kokon-mcp.exe","args":[]}'

• Every result returns the absolute path of the saved file, its size, seed and generation metadata.
• Paths may be absolute or relative to the project (CLAUDE_PROJECT_DIR). Reads and writes are limited to the project folder, Kokon's output folder and folders listed in QLS_MCP_ALLOWED_DIRS (separated by semicolons). Existing files are never overwritten.
• Images are not sent back to the model by default; they stay on disk. Pass include_preview: true to include a small JPEG preview.
• upscale_image takes scale (default 2) or width/height (up to 8192 px).
• Progress is reported through MCP progress notifications. Claude Code's default tool timeout is 30 minutes (MCP_TOOL_TIMEOUT).
• Without the desktop window open, the model is unloaded after 15 idle minutes (Settings → General).

Base URL http://127.0.0.1:39151/api/v1. Every call except /ping needs Authorization: Bearer <token>, with the token from %LOCALAPPDATA%\KokonData\service.json (Mac: ~/Library/Application Support/KokonData/service.json). Requests that carry a browser Origin header are refused.

$i = Get-Content "$env:LOCALAPPDATA\KokonData\service.json" | ConvertFrom-Json
$h = @{ Authorization = "Bearer $($i.token)" }
Invoke-RestMethod -Method Post "http://127.0.0.1:$($i.port)/api/v1/generate" -Headers $h `
  -ContentType 'application/json' -Body '{"prompt":"a lighthouse at dusk, 16:9","quality":"fast"}'

Simple-operation fields: prompt, image / images[], mask, action (edit|remove|replace|add, inpainting), width, height, aspect_ratio, quality (fast|balanced|quality), seed, output_path, preserve_dimensions, private, left/right/top/bottom + units (pixels|percent) for outpainting, scale for upscaling. Full requests (/jobs) also accept "mode": "upscale" with "upscale": {"scale" | "width"/"height"}.

SmartScreen shows this for new apps that don't have a download history yet. Click More info → Run anyway. You can check the installer against the SHA-256 hash listed in the release notes, or build it yourself.

Kokon is not notarized by Apple (that needs a paid Apple developer account), so macOS blocks it the first time. You only do this once; in-app updates don't trigger it again.

1. Open Kokon. macOS says “Kokon” Not Opened: click Done (not Move to Trash).

   

2. Open System Settings → Privacy & Security and scroll down to Security. Next to “Kokon” was blocked to protect your Mac, click Open Anyway, then confirm with your password or Touch ID.

   

3. Open Kokon again and click Open in the last prompt.

You can also build it yourself.

Only to download the models. After that Kokon works fully offline. If you are online it checks once a day for a new version, which you can turn off on the welcome screen or in Settings → General.

AMD and Intel: in beta. The setup screen installs stable-diffusion.cpp's Vulkan build for them, which uses the graphics driver you already have. It works on NVIDIA cards, but it has not been verified on a real AMD or Intel card yet; integrated graphics are not supported. Please open an issue with your card and how it went.

Mac: yes, in beta, on Apple Silicon (M1 or newer) with macOS 26. It runs on a 16 GB Mac in a lighter mode, but slowly (about 4 minutes per 1-megapixel image on an M2 Pro); 32 GB or more and a Pro, Max or Ultra chip are recommended. See the requirements and docs/platforms.md.

Yes, in beta since 0.9.3. Setup picks the 8 GB preset: the same files as the 12 GB one, with smaller working sizes, so images are made at about 1 megapixel (then enlarged). Users report it works on an RTX 3060 Ti and on an RTX 5050 Laptop, where an edit takes 1–2 minutes. The text encoder runs from system RAM, so 16 GB of RAM or more is recommended. If you try it, please tell us how it runs in an issue.

Not with the default model. Kokon's code is open source (see License), but the image model has its own license: Qwen-Image 2.1 and its Turbo model are released under the Qwen Research License, which allows research and evaluation only, no commercial use. That includes selling or using commercially the images you make with it. For commercial use, ask the Qwen team for a license (model-business@notice.qwencloud.com).

The Qwen3-VL text encoder is Apache-2.0. The default upscaler, Superscale-SP by Nmkd, is WTFPL, and the experimental MoSR by Philip Hofmann is CC BY 4.0: both allow commercial use. The optional UltraSharp upscaler is CC BY-NC-SA 4.0, non-commercial only.

HEIC/HEIF photos open like any other image. On a Mac they are decoded by macOS itself. On Windows, Microsoft's HEIF Image Extensions and HEVC Video Extensions must be installed.

iPhone photos with an HDR gain map (iOS 18+) show a Keep HDR switch in Advanced, which is on by default. Edits of such photos are saved as Ultra HDR JPEG: Chrome, Edge, Android and recent Apple systems show them in HDR, and every other viewer shows a normal JPEG. This needs ffmpeg 7.1+ on PATH; without it the result is saved in SDR and the job's notes say why.

By default Superscale-SP by Nmkd (ESRGAN), downloaded by the setup screen; on a Mac, Lanczos, because AI upscalers take minutes there (Superscale-SP: 5 min 45 s to enlarge a 1024×1024 image to 2048×2048 on an M2 Pro, against about a second). Pick another one in the Advanced menu next to the prompt, or in Settings → Models; Compare upscalers there shows each one on the same crops (a face, a JPEG photo, a night street, text, a landscape, a 4× upscale):

• Superscale-SP (default): sharp and natural on most images; on JPEG photos and dark areas it can draw a faint grid.
• MoSR (experimental, 17 MB, comes with the app): the fastest, good for 4× upscales, but on clean images enlarged less than about 3× it draws a fine grid. Kokon contributed it to stable-diffusion.cpp (pull request #2128, merged 2026-10-12).
• UltraSharp (optional download): very clean, but smooths skin into an artificial look and can invent lines. Non-commercial license.
• Lanczos: a plain resize, never invents anything.

Upscaler strength (0–100 %) mixes the upscaler's result with a plain resize, to tone down texture it invents. Settings → Models also has Shrink the image before upscaling, which gives the upscaler a smaller image, like the ones it was trained on.

Windows: Settings → Apps → Installed apps → Kokon → Uninstall. The uninstaller asks whether to delete the downloaded models and app data too (%LOCALAPPDATA%\KokonData).

Mac: drag Kokon from Applications to the Trash. To free the model space too, delete ~/Library/Application Support/KokonData.

Your images stay in your Pictures folder.

If a download fails, the setup screen shows the file's download page and target folder so you can fetch it by hand. For anything else, please open an issue with your GPU (or Mac model), driver or macOS version and the log from KokonData/logs (see the table above).

Windows: Rust (stable, MSVC), Node 22+, Visual Studio Build Tools and WebView2.

npm install
cargo test -p qls-core            # core unit tests
npx vitest run                    # UI logic tests
cd mcp; npx vitest run; cd ..     # MCP tests (includes a stdio protocol test)
npx tauri dev                     # run the desktop app in development
powershell -ExecutionPolicy Bypass -File scripts\build-release.ps1   # installer

Mac (Apple Silicon, macOS 26+): Xcode Command Line Tools, Rust and Node 22+.

bash scripts/dev/mac-dev.sh --check   # check the prerequisites
bash scripts/dev/mac-dev.sh           # build and run the app in development
bash scripts/build-release-mac.sh     # Kokon.app + .dmg in dist-release/

Publishing a release (signed in-app updates for both platforms) is described in docs/releasing.md.

flowchart TB
    UI["<b>Kokon</b><br>Tauri 2 + React"]
    MCP["<b>kokon-mcp</b><br>MCP over stdio"]
    S["Scripts and other apps"]
    SVC["<b>kokon-service</b><br>planner · preprocessing · job queue · gallery<br><code>127.0.0.1:39151/api/v1</code>"]
    SD["<b>sd-server</b><br>stable-diffusion.cpp (CUDA · Vulkan · Metal)<br><code>127.0.0.1:39150</code>"]
    UI -- "HTTP + SSE, token" --> SVC
    MCP -- "HTTP, token" --> SVC
    S -- "HTTP, token" --> SVC
    SVC -- "native async API" --> SD

The Rust core (crates/qls-core) holds all the logic: geometry, image processing, planning, the inference adapter, the job queue and the gallery. The service, the desktop app and the MCP server are thin layers on top. See the engineering notes for a module map and the backend facts each default is based on.