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.
TypeScript ai-photo-editorcomfyui-alternativegenerative-fillimage-editingimage-generationinpaintinglinuxlocal-aimacosmcpmcp-servernano-banana-alternativeofflinephoto-editorprivacyqwen-imageqwen-image-2-1stable-diffusion-cppvulkanwindows
docs: Linux plan, status and engine upkeep; Vulkan engine pinned; build script needs rustup cargo
Gabriele Lozupone6397b3c6fa69
diff --git a/crates/qls-core/src/catalog.rs b/crates/qls-core/src/catalog.rsindex 28e656d..b31ce11 100644--- a/crates/qls-core/src/catalog.rs+++ b/crates/qls-core/src/catalog.rs@@ -233,9 +233,9 @@ const LINUX_CUDART_SIZE: u64 = 0;#[cfg(target_os = "linux")]const LINUX_CUDART_SHA256: &str = "";#[cfg(target_os = "linux")]-const LINUX_VULKAN_SIZE: u64 = 0;+const LINUX_VULKAN_SIZE: u64 = 38_456_278;#[cfg(target_os = "linux")]-const LINUX_VULKAN_SHA256: &str = "";+const LINUX_VULKAN_SHA256: &str = "d998e8b831e9228571e7203020f503a3fea70b87f57ba5e0a106ae4e3afb7f60";/// Same commit, macOS build: universal binary with the Metal shaders embedded, needs/// macOS 26. Ad-hoc signed; downloaded by the app (not a browser) it gets no quarantine flag.diff --git a/docs/linux.md b/docs/linux.mdnew file mode 100644index 0000000..a99a7db--- /dev/null+++ b/docs/linux.md@@ -0,0 +1,109 @@+# Linux: plan, status and engine upkeep++Kokon supports **Linux from 0.9.3** (x86_64, `.deb` + `.rpm`, NVIDIA CUDA and Vulkan for AMD/Intel),+next to Windows and macOS. Every release from now on ships all three.++## The plan (decided 2026-10-16)++The app is already client/server: the UI talks to `kokon-service` only over HTTP (base URL + token,+`src/lib/api.ts`); the desktop shell just starts the service and hands the UI `127.0.0.1` + token+(`src-tauri/src/lib.rs` `connect`). So the three steps are one product started three ways:++1. **Native Linux app** (this document, 0.9.3). Same app as Windows/Mac: local service on 127.0.0.1.+2. **Headless server + browser UI**, then **Docker**. `kokon-service` serves the built UI itself;+ network access is opt-in, off by default, with a real password (rate-limited) before anything+ listens beyond localhost; recommend Tailscale/VPN over exposing it. Docker = the same Linux build+ without a window, model folders mounted as volumes.+3. **Kokon as a client**: the desktop app (Windows/Mac/Linux) connects to a Kokon server elsewhere.+ "Connect to a server" in Setup/Settings (address + password); `connect` returns the remote URL.+ Needs: copy-image by bytes instead of a local path (`Stage.tsx` → `copy_image`), hide "Show in+ folder"/"Open logs", import/export by upload/download instead of paths (`api.ts` `importPath`,+ `exportGeneration`), setup's "Use models I already have" picks a folder **on the server**, and a+ client/server version check.++Rough effort for one person: 1 = days, 2 = 3–5 days, 3 = about a week. Order: 1 → 2 (+Docker) → 3.+Public promise: issue #15 comment (2026-10-16). #22 closed as its duplicate.++## 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`).+- `engine.json` (engine updates without an app release) lists upstream's Windows/Mac builds only, so+ **Linux ignores it** (`apply_engine_release` returns early). Linux engines change with app releases+ until the manifest gets Linux entries (to do, below).+- First build: run 38885751650 (2026-10-16); Vulkan finished in 12 min, CUDA takes over an hour.++## Engine upkeep: check at every release (and when engine.json moves)++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. Same pipeline later for #24: a Mac engine built for macOS 15 (planned 0.9.4).++## Building and testing the Linux app++- Build machine: **WSL Ubuntu-22.04** on the dev PC (installed 2026-10-16; sees the RTX 5070 Ti through+ the Windows driver, so CUDA can be tested; windows open through WSLg). Clone on the Linux disk:+ `git clone -b <branch> /mnt/c/AI/qwen-local-studio ~/kokon` (never build from /mnt/c: npm would replace+ the Windows node_modules). Ubuntu's `cargo` package is too old; use rustup (`. ~/.cargo/env`).+- Release: `bash scripts/build-release-linux.sh --setup` once, then `bash scripts/build-release-linux.sh`+ → `dist-release/Kokon_<v>_amd64.deb`, `Kokon-<v>-1.x86_64.rpm`, `updater-linux-x86_64-{deb,rpm}.json`.+ Signed with the same updater key as Windows/Mac (`~/.tauri/kokon-updater.key`, also found under+ /mnt/c/Users/*/.tauri).+- Quick run without packaging: `npm run build && cargo build -p kokon --release --features+ tauri/custom-protocol && ./target/release/kokon` (without the feature the window loads the dev server+ and shows "Could not connect to localhost").+- In-app updates work on Linux: tauri-plugin-updater 2.13 installs `.deb`/`.rpm` through pkexec;+ `latest.json` needs `linux-x86_64-deb` and `linux-x86_64-rpm` entries.+- 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 (Vulkan OK: loads in WSL, glibc ≤ 2.34; CUDA building).+- ✅ Kokon branch `linux` (commit 9d8ed7f, local): 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.3 for Linux"+- [ ] CUDA build finished → fill `LINUX_CUDA_*` / `LINUX_CUDART_*` (Vulkan values already in), commit+ with the script's cargo check fix.+- [ ] 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.+- [ ] Merge `linux` into master (no app change for Windows/Mac), add the .deb/.rpm to the v0.9.3 release,+ merge the Linux entries into v0.9.3's `latest.json` (download it, add the two platforms, re-upload;+ Windows/Mac entries unchanged).+- [ ] 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.++Later+- [ ] engine.json Linux entries (fork URLs) so Linux gets engine updates without an app release.+- [ ] 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.diff --git a/scripts/build-release-linux.sh b/scripts/build-release-linux.shindex 6858a1d..38c3ae9 100644--- a/scripts/build-release-linux.sh+++ b/scripts/build-release-linux.sh@@ -20,7 +20,8 @@ if [ "${1:-}" = "--setup" ]; thensudo apt-get updatesudo apt-get install -y build-essential curl wget file pkg-config libssl-dev libgtk-3-dev \libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev libxdo-dev patchelf- command -v cargo >/dev/null || curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y+ # Not Ubuntu's cargo package (too old for this workspace): rustup's current stable.+ command -v rustup >/dev/null || [ -x "$HOME/.cargo/bin/rustup" ] || curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -yif ! node --version 2>/dev/null | grep -q '^v2[2-9]'; thencurl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -sudo apt-get install -y nodejs@@ -30,6 +31,7 @@ if [ "${1:-}" = "--setup" ]; thenfi. "$HOME/.cargo/env" 2>/dev/null || true+cargo --version | grep -qE "^cargo 1.(8[4-9]|9[0-9]|[1-9][0-9]{2})" || { echo "✗ $(cargo --version) is too old (Ubuntu's package?): sudo apt remove cargo rustc, then run with --setup."; exit 1; }for c in cargo node npm pkg-config; do command -v "$c" >/dev/null || { echo "✗ $c not found: run with --setup first."; exit 1; }; donepkg-config --exists webkit2gtk-4.1 || { echo "✗ webkit2gtk-4.1 not found: run with --setup first."; exit 1; }