Skip to content

armgit / kokon

Public Imported from GitHub
0

Edit photos by describing the change, on your own GPU. A free, open-source alternative to Nano Banana and ChatGPT image editing: photos stay on your computer, no daily limit. One installer for Windows, Mac and Linux sets up the best open model (Qwen-Image 2.1). MCP server for AI agents.

docs: engines are Kokon's own kokon-992 build on every platform

Gabriele Lozupone162f3aed4da0
diff --git a/docs/linux.md b/docs/linux.md
index 9c5f5b0..3eb7878 100644
--- a/docs/linux.md
+++ b/docs/linux.md
@@ -32,50 +32,46 @@ settled before work on 0.11.0 starts.
## Why Kokon builds its own Linux engine
Upstream stable-diffusion.cpp publishes Linux zips for Vulkan, ROCm and CPU only, **no CUDA**, built on
-Ubuntu 24.04: they need **glibc 2.38**, so they don't run on Ubuntu 22.04 or Debian 12. Kokon builds the
-exact upstream commit it ships on **Ubuntu 22.04** (glibc 2.35; the Vulkan build needs ≤ 2.34) with
-upstream's own flags and CUDA architectures (`61;70;75;80;86;89;90;100;120`, CUDA 12.8).
-
-- Fork: `GabrieleLozupone/stable-diffusion.cpp`, branch **`kokon-linux`** = the upstream commit + one
- commit adding `.github/workflows/kokon-linux.yml`.
-- A push to `kokon-linux` builds Vulkan + CUDA, smoke-tests that the engine loads on Ubuntu 22.04/24.04,
- Debian 12, Fedora 40/42, and publishes prerelease **`kokon-linux-<commit>`** with
- `sd-master-<commit>-bin-Linux-Ubuntu-22.04-x86_64-{vulkan,cuda12}.zip`,
- `cudart-sd-bin-linux-cu12-x64.zip` (libcudart/libcublas/libcublasLt, next to the engine; RPATH
- `$ORIGIN`) and `SHA256SUMS.txt`.
-- The app pins these in `crates/qls-core/src/catalog.rs` (`#[cfg(target_os = "linux")]` versions of
- `ENGINE_CUDA`, `CUDA_RUNTIME`, `ENGINE_VULKAN`, plus `LINUX_*_SIZE/SHA256`).
-- **Since 0.10** the engines come from the single workflow `kokon.yml` on fork branch `kokon` (release
- `kokon-<n>-<commit>`, every platform), and `engine.json` has Linux entries (`kokon.linux_cuda`,
- `kokon.linux_vulkan`), so Linux gets engine updates without an app release. The CUDA runtime stays
- pinned to `kokon-linux-1d0a58a`. The `kokon-linux` branch and its releases serve apps up to 0.9.4.
-- First build: run 38885751650 (2026-10-16): Vulkan 12 min, CUDA 1 h 32 min. Its CUDA smoke test was
- wrong (sd-server links libcuda.so.1, which only the NVIDIA driver provides, so it can't start in CI);
- the release was published by hand from that run's artifacts after a real check in WSL (RTX 5070 Ti
- found, CUDA backend loads). The workflow now only checks libraries for CUDA and never replaces a
- published release (rebuilds aren't byte-identical and the app pins SHA-256).
+Ubuntu 24.04: they need **glibc 2.38**, so they don't run on Ubuntu 22.04 or Debian 12. Kokon builds its
+engine on **Ubuntu 22.04** (glibc 2.35; the Vulkan build needs ≤ 2.34) with upstream's own flags and CUDA
+architectures (`61;70;75;80;86;89;90;100;120`, CUDA 12.8).
+
+**Since 0.10 (current):** one workflow builds every platform's engine.
+
+- Fork: `GabrieleLozupone/stable-diffusion.cpp`, branch **`kokon`** = upstream (`UPSTREAM_BASE`, now
+ b13a482) + the text-generation commits for Prompt+ + workflow **`kokon.yml`**. ggml comes from Kokon's
+ ggml fork (branch `sdcpp-cuda-graphs-opt-in`, CUDA graphs only for reused graphs).
+- Running `kokon.yml` with `create_release` publishes **`kokon-<n>-<commit>`** (now
+ [`kokon-992-dfaab76`](https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/tag/kokon-992-dfaab76)):
+ `sd-kokon-<commit>-bin-Linux-Ubuntu-22.04-x86_64-{cuda12,vulkan,cpu,rocm-10.1.0}.zip`, the Windows and
+ macOS 15 zips, `cudart-sd-bin-{linux,win}-cu12-x64.zip` and `SHA256SUMS.txt`. A published release is
+ never replaced (rebuilds aren't byte-identical and the app pins SHA-256).
+- The app pins it in `crates/qls-core/src/catalog.rs` (`ENGINE_TAG`, Linux `ENGINE_CUDA` / `ENGINE_VULKAN`),
+ and `engine.json` lists it under the `kokon` key (`linux_cuda`, `linux_vulkan`), so Linux gets engine
+ updates without an app release. The Linux CUDA runtime (`CUDA_RUNTIME`) stays pinned to
+ `kokon-linux-1d0a58a`; it is only downloaded once.
+
+**Up to 0.9.4 (history; these releases still serve old apps, don't delete them):** branch `kokon-linux`
+(upstream commit + `kokon-linux.yml`) published `kokon-linux-<commit>`, and `kokon-macos.yml` published
+`kokon-macos-<commit>` for macOS 15. First build: run 38885751650 (2026-10-16): Vulkan 12 min, CUDA
+1 h 32 min. Its CUDA smoke test was wrong (sd-server links libcuda.so.1, which only the NVIDIA driver
+provides, so it can't start in CI); the release was published by hand after a real check in WSL. The
+workflows now only check libraries for CUDA.
## Engine upkeep: check at every release (and when engine.json moves)
-> Up to 0.9.4. From 0.10 the fork branch `kokon` (one workflow, every platform) replaces the steps
-> below: rebase it on upstream, update `UPSTREAM_BASE` in `kokon.yml`, run it with `create_release`.
-
-Upstream moves fast (2026-10-16: master-968-8cd731e, 4 commits after our 1d0a58a, including a Vulkan
-direct-convolution fix and FLUX.3 Klein). When Windows/Mac move to a newer engine, Linux must follow:
-
-1. `gh api repos/leejet/stable-diffusion.cpp/compare/<our commit>...master` and the upstream releases.
-2. In the fork clone: `git fetch upstream`, `git switch kokon-linux`, `git rebase --onto <new commit>
- <old commit>` (keeps only the workflow commit), set `ENGINE_SHORT` in the workflow, push to `fork`.
-3. Wait for the run; it publishes `kokon-linux-<new commit>`. Check the glibc report in the build log.
-4. In Kokon: update the Linux URLs, sizes and SHA-256 in `catalog.rs` with the `ENGINE_TAG` bump,
- test once in WSL (engine download + one image), release.
-5. **Mac too (#24, from 0.9.4):** the same push runs `kokon-macos.yml` (same `ENGINE_SHORT` to set),
- which builds upstream's Mac job with `CMAKE_OSX_DEPLOYMENT_TARGET=15.0`, checks `minos` 15.0, starts
- the engine on a macOS 15 runner and publishes prerelease `kokon-macos-<commit>`
- (`sd-master-<commit>-bin-Darwin-macOS-15.0-arm64.zip`). Pin it in `catalog.rs` (`ENGINE_METAL`,
- `MACOS_METAL_*`) and add it to `engine.json` as `metal_macos15`: apps from 0.9.4 on a Mac take
- engine updates only from that entry (`metal` stays upstream's build for apps up to 0.9.3, on 26).
- The two workflows ignore each other's file, so editing one doesn't rebuild the other.
+Upstream moves fast. Every platform follows the same release, so:
+
+1. `gh api repos/leejet/stable-diffusion.cpp/compare/<UPSTREAM_BASE>...master` and the upstream releases.
+2. In the fork clone: `git fetch upstream`, `git switch kokon`, rebase the Kokon commits onto the new
+ upstream commit, set `UPSTREAM_BASE` in `kokon.yml`, push to `fork`.
+3. Run `kokon.yml` with `create_release`; it publishes `kokon-<n>-<new commit>`. Check the glibc report
+ in the build log.
+4. Test on Windows (CUDA + Vulkan), Linux (WSL: engine download, one image, one Prompt+ job) and a Mac.
+5. Ship it: either bump `ENGINE_TAG` and the pins in `catalog.rs` with an app release, or edit the
+ `kokon` key in `engine.json` on master (digests: `gh release view <tag> -R
+ GabrieleLozupone/stable-diffusion.cpp --json assets`). Details in
+ [engineering-notes.md](engineering-notes.md), "Engine updates".
## Building and testing the Linux app
@@ -95,34 +91,15 @@ direct-convolution fix and FLUX.3 Klein). When Windows/Mac move to a newer engin
- Package dependencies (tauri.linux.conf.json): libssl3 / openssl-libs (reqwest native-tls), libgomp,
libvulkan1 / vulkan-loader. HEIC photos can't be opened on Linux yet (message shown).
-## Status (2026-10-16)
-
-Done
-- ✅ Fork workflow + first engine build; prerelease `kokon-linux-1d0a58a` published (Vulkan loads on
- Ubuntu 22.04/24.04, Debian 12, Fedora 40/42; CUDA finds the RTX 5070 Ti in WSL).
-- ✅ Kokon `linux` work (9d8ed7f…b4e6802), merged into master and pushed 10-16: Linux engines in the catalog, manifest ignored on
- Linux, AMD GPU detection from /sys/class/drm + pci.ids names, deb/rpm config, bundled resources in
- /usr/lib/Kokon, logs-folder path, kokon-mcp Linux build, updater manifest Linux entries,
- build-release-linux.sh. Windows tests still pass (core 185, UI 128).
-- ✅ First Linux compile in WSL OK; app opens, detects RTX 5070 Ti 16 GB, picks CUDA + 16 GB preset,
- install folder ~/.local/share/KokonData/sdcpp.
-
-To do for 0.9.4 (Linux + fixes for every platform)
-- ✅ Engine sizes and SHA-256 pinned in catalog.rs (from GitHub's asset digests).
-- [ ] Full test in WSL: Install → CUDA engine download → one image + one edit on the 5070 Ti.
-- [ ] `build-release-linux.sh` end to end (tests, kokon-mcp, deb + rpm, signatures). Install the .deb in
- a clean WSL distro; ideally also Fedora (`wsl --install -d FedoraLinux-42`) and Debian.
-- [ ] Ship as **0.9.4 on all three platforms** (not as extra 0.9.3 assets: one version = one code).
- The `linux` branch also fixes, for everyone, square 2K upscales that fell back to Lanczos and the
- prompt box height on Linux. `latest.json` gets `linux-x86_64-deb` / `linux-x86_64-rpm` entries.
-- [ ] README (platform table, badges, install commands `sudo apt install ./Kokon_…deb` /
- `sudo dnf install ./Kokon-…rpm`), site download button + FAQ, release notes section, bug-report
- template OS list, docs/platforms.md.
-- [ ] Announce: #15 comment (ping giveen, swingtempo), Reddit "Update" lines, X; later r/selfhosted with
- the server mode.
+## Status (2026-10-20)
+
+- ✅ **0.9.4** (2026-10-16): first Linux release, `.deb` + `.rpm`, engine `kokon-linux-1d0a58a`.
+- ✅ **0.10.0** (2026-10-20): Linux on Kokon's own `kokon-992-dfaab76` like every platform (Prompt+
+ included), Linux entries in `engine.json`; crashed engine no longer leaves a job waiting forever (#28).
+- Builds: WSL Ubuntu-22.04, `build-release-linux.sh` (section above). CUDA tested in WSL on the
+ RTX 5070 Ti; LoRA (beta) not tested on Linux by us.
Later
-- [x] engine.json Linux entries (fork URLs) so Linux gets engine updates without an app release (0.10, `kokon` key).
- [ ] Real-hardware reports: AMD on Linux (swingtempo R9700, alean200), a non-WSL NVIDIA machine.
- [ ] AppImage? Not planned (large, and deb/rpm cover the main distros).
-- [ ] Steps 2 and 3 of the plan above.
+- [ ] Steps 2 and 3 of the plan above (0.11.0; design under review).
diff --git a/docs/platforms.md b/docs/platforms.md
index 9a95045..c9ed8d1 100644
--- a/docs/platforms.md
+++ b/docs/platforms.md
@@ -1,16 +1,20 @@
# Platforms: engines, requirements and what is verified
-Kokon runs Qwen-Image 2.1 through stable-diffusion.cpp. Each platform uses a prebuilt engine
-from the same pinned release ([master-929-3f8527a](https://github.com/leejet/stable-diffusion.cpp/releases/tag/master-929-3f8527a)),
-so model behaviour is identical everywhere; only speed and memory differ.
-
-| Platform | Engine | Status |
+Kokon runs Qwen-Image 2.1 through stable-diffusion.cpp. Since 0.10 every platform uses Kokon's own
+build from one release of the fork ([kokon-992-dfaab76](https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/tag/kokon-992-dfaab76):
+upstream b13a482 plus text generation for Prompt+, branch `kokon`, workflow `kokon.yml`), so model
+behaviour is identical everywhere; only speed and memory differ. The image side is upstream's code.
+`engine.json` (key `kokon`) can move every platform to a newer release without an app update; see
+the engine section of [engineering-notes.md](engineering-notes.md). Apps up to 0.9.4 used upstream's
+releases (Windows, macOS 26) and the `kokon-linux` / `kokon-macos` builds (Linux, macOS 15).
+
+| Platform | Engine (kokon-992-dfaab76) | Status |
| --- | --- | --- |
-| Windows + NVIDIA | CUDA 12 build | ✅ verified (RTX 5070 Ti 16 GB, RTX 5070 12 GB) |
-| Windows + AMD / Intel | Vulkan build (30 MB, uses the driver's Vulkan runtime) | 🟡 beta: works on NVIDIA (RTX 5070 Ti, 2K/20 steps, slower than CUDA); first AMD user report: RX 9060 XT 16 GB, 16:9 1080p Balanced ~80 s on the first image (incl. model load), no errors; Intel to verify |
-| macOS + Apple Silicon | Metal build (universal binary, shaders embedded; Kokon's own build for macOS 15 from 0.9.4) | 🟡 beta: packaged 0.9.0 runs on an M2 Pro 16 GB (Turbo: ~1 MP in ~4 min 20 s, lightest mode) |
-| Windows + AMD via ROCm | ROCm build | ✗ not planned: open crashes (#2008), DLL conflicts (#2012), black images with k-quants (#1385) |
-| Linux x86-64 (.deb / .rpm) | Kokon's own CUDA 12.8 and Vulkan builds of the same commit (Ubuntu 22.04, glibc 2.35) | 🟡 beta from 0.9.4: CUDA verified on an RTX 5070 Ti under WSL; Vulkan loads on Ubuntu 22.04/24.04, Debian 12, Fedora 40/42. Details in [linux.md](linux.md) |
+| Windows + NVIDIA | CUDA 12.8 build with CUDA graphs (runtime DLLs from upstream's `cudart-sd-bin-win-cu12-x64.zip`) | ✅ verified (RTX 5070 Ti 16 GB, RTX 5070 12 GB) |
+| Windows + AMD / Intel | Vulkan build (29 MB, uses the driver's Vulkan runtime) | 🟡 beta: works on NVIDIA (RTX 5070 Ti, 2K/20 steps, slower than CUDA); first AMD user report: RX 9060 XT 16 GB, 16:9 1080p Balanced ~80 s on the first image (incl. model load), no errors; Intel to verify |
+| macOS + Apple Silicon | Metal build, macOS 15.0+, universal binary, shaders embedded (Macs on 26 use it too) | 🟡 beta: packaged 0.9.0 runs on an M2 Pro 16 GB (Turbo: ~1 MP in ~4 min 20 s, lightest mode) |
+| Windows + AMD via ROCm | ROCm build (published by the workflow, not used by Kokon) | ✗ not planned: open crashes (#2008), DLL conflicts (#2012), black images with k-quants (#1385) |
+| Linux x86-64 (.deb / .rpm) | CUDA 12.8 (CUDA graphs) and Vulkan builds on Ubuntu 22.04 (glibc 2.35); CUDA runtime still from `kokon-linux-1d0a58a` | 🟡 beta from 0.9.4: CUDA verified on an RTX 5070 Ti under WSL; Vulkan loads on Ubuntu 22.04/24.04, Debian 12, Fedora 40/42. Details in [linux.md](linux.md) |
## How the app sizes itself (all platforms)
@@ -27,7 +31,7 @@ budget (largest working size per quality level). Nothing is tuned per platform.
## Windows: AMD and Intel (Vulkan, beta)
-- Engine: `sd-master-3f8527a-bin-win-vulkan-x64.zip`, installed into `<sdcpp>\engine-vulkan`,
+- Engine: `sd-kokon-dfaab76-bin-win-vulkan-x64.zip`, installed into `<sdcpp>\engine-vulkan`,
next to the CUDA build (switching engines needs no re-download).
- Launch: `--backend vulkan0`, flash attention, q8_0 prefix cache. No SageAttention (CUDA only).
- Requirements: a discrete GPU with **12 GB+ VRAM** (RX 6700 XT 12 GB / 7700 XT and up,
@@ -50,6 +54,9 @@ pass. Kokon uses CFG 1, which is one pass per step.
| --- | --- | --- |
| **Chip** | Apple M1 or newer (Intel Macs: no) | M-series Pro / Max / Ultra |
| **macOS** | 15 Sequoia (Kokon's engine build; upstream's needs 26) | latest |
+
+The Mac paragraphs below that say "our exact engine build" or "the same engine build" mean the
+upstream release Kokon used up to 0.9.4 (master-929); the measurements were taken on it.
| **Unified memory** | 16 GB: works, but slowly (lightest mode, ~1 MP, ~4–5 min on an M2 Pro) | 32 GB+ (everything stays loaded, Quality 2K) |
| **Disk** | 15 GB free | 25 GB on the internal SSD |