Improve Linux build stability and model download robustness

Cross-platform build improvements:
- Add Linux-specific linker configuration in Cargo config
- Use bundled whisper-rs-sys bindings to avoid libclang/libLLVM coupling
- Update .envrc for better cross-platform compiler detection
- Add ELF interpreter patching in build.sh for Nix-built binaries

Model downloader improvements:
- Add atomic file operations with temp file cleanup
- Implement proper checksum verification with error recovery
- Add retry logic with exponential backoff for failed downloads
- Clean up stale temporary files before new downloads
- Verify models exist before listing as downloaded

These changes ensure stable builds across different Linux environments
(Nix, system, mixed) and more reliable model downloads.

Fix Windows build by making WHISPER_DONT_GENERATE_BINDINGS target-specific

The WHISPER_DONT_GENERATE_BINDINGS flag was set globally, causing
whisper-rs-sys to use bundled (Linux) bindings on Windows, which led
to compilation errors due to platform-specific struct size mismatches.

Now only Linux and macOS targets use bundled bindings, while Windows
generates bindings at build time as intended.

Fix CI builds by setting WHISPER_DONT_GENERATE_BINDINGS env var

The target-specific environment variables in .cargo/config.toml only
apply when building with explicit --target flags. CI builds without
--target flags don't pick up these settings, causing whisper-rs-sys
to try building from source and fail.

Solution: Set WHISPER_DONT_GENERATE_BINDINGS=1 as an environment
variable in the CI and release workflows for Linux and macOS.
Windows correctly generates bindings at build time and doesn't
need this flag.

Fix CI cache issue preventing WHISPER_DONT_GENERATE_BINDINGS from taking effect

- Update cache key from v1 to v2 to bust old cache
- Add explicit cargo clean -p whisper-rs-sys to force rebuild with correct env
- This ensures whisper-rs-sys uses bundled bindings instead of building from source

fix

Fix TUI default model to use ggml-base.en without .bin extension

The TUI was using 'ggml-base.en.bin' as the default model path, but
the model registry and Rust code use model IDs without file extensions
(e.g., 'ggml-base.en'). This caused the TUI to create configs with
incorrect model paths.

Now matches the Rust default in src/config.rs

Author: kssgarcia

.cargo/config.toml

@@ -1,6 +1,9 @@
 [target.aarch64-apple-darwin]
 linker = "/usr/bin/clang"
 
+[target.x86_64-unknown-linux-gnu]
+linker = "/usr/bin/cc"
+
 [target.x86_64-apple-darwin]
 linker = "/usr/bin/clang"
 
@@ -13,3 +16,18 @@ CC_x86_64_apple_darwin = "/usr/bin/clang"
 CXX_x86_64_apple_darwin = "/usr/bin/clang++"
 # Disable BLAS in whisper.cpp to avoid symbol mismatch with macOS Accelerate framework
 GGML_BLAS = "OFF"
+
+# Use bundled whisper-rs-sys bindings on Linux/macOS to avoid runtime libclang/libLLVM coupling.
+# This keeps builds stable across Linux/macOS (including mixed Nix/system shells).
+# Windows generates bindings at build time, so don't set this there.
+[target.x86_64-unknown-linux-gnu.env]
+WHISPER_DONT_GENERATE_BINDINGS = "1"
+
+[target.aarch64-unknown-linux-gnu.env]
+WHISPER_DONT_GENERATE_BINDINGS = "1"
+
+[target.aarch64-apple-darwin.env]
+WHISPER_DONT_GENERATE_BINDINGS = "1"
+
+[target.x86_64-apple-darwin.env]
+WHISPER_DONT_GENERATE_BINDINGS = "1"

.envrc

@@ -1,7 +1,36 @@
-# macOS SDK path for linking
-export SDKROOT=$(xcrun --show-sdk-path)
-export LIBRARY_PATH="/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/lib:${LIBRARY_PATH:-}"
+# Cross-platform compiler/tooling environment.
+# Keep per-OS logic isolated so local shell setup does not break other targets.
 
-# Force use of system clang instead of GCC (important for macOS)
-export CC=clang
-export CXX=clang++
+case "$(uname -s)" in
+Darwin)
+  # macOS SDK path for linking
+  if command -v xcrun >/dev/null 2>&1; then
+    export SDKROOT="$(xcrun --show-sdk-path)"
+    export LIBRARY_PATH="/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/lib:${LIBRARY_PATH:-}"
+  fi
+
+  # Prefer clang toolchain on macOS
+  export CC=clang
+  export CXX=clang++
+  ;;
+Linux)
+  # Prefer clang toolchain on Linux as well (used by native deps / CMake).
+  if command -v clang >/dev/null 2>&1; then
+    export CC=clang
+  fi
+  if command -v clang++ >/dev/null 2>&1; then
+    export CXX=clang++
+  fi
+
+  # Optional hint for bindgen-based crates.
+  # onevox uses bundled whisper bindings in Cargo config, so libclang is not required.
+  if command -v llvm-config >/dev/null 2>&1; then
+    _llvm_libdir="$(llvm-config --libdir 2>/dev/null || true)"
+    if [ -n "${_llvm_libdir}" ] && [ -d "${_llvm_libdir}" ]; then
+      export LIBCLANG_PATH="${_llvm_libdir}"
+    fi
+  elif [ -d /usr/lib ]; then
+    export LIBCLANG_PATH="/usr/lib"
+  fi
+  ;;
+esac

.github/workflows/ci.yml

@@ -43,7 +43,7 @@ jobs:
         uses: actions/cache@v4
         with:
           path: target
-          key: ${{ runner.os }}-cargo-build-target-${{ hashFiles('**/Cargo.lock') }}
+          key: ${{ runner.os }}-cargo-build-target-v2-${{ hashFiles('**/Cargo.lock') }}
 
       - name: Install Linux system dependencies
         if: runner.os == 'Linux'
@@ -58,13 +58,21 @@ jobs:
             libxfixes-dev \
             libxi-dev \
             libxtst-dev
+          # Use bundled whisper-rs-sys bindings on Linux
+          echo "WHISPER_DONT_GENERATE_BINDINGS=1" >> $GITHUB_ENV
+          # Clean whisper-rs-sys to ensure it rebuilds with correct env
+          cargo clean -p whisper-rs-sys || true
 
       - name: Set whisper.cpp build flags for macOS
         if: runner.os == 'macOS'
         run: |
           # Use generic ARM64 target instead of native to avoid i8mm issues on CI
           echo "CFLAGS=-march=armv8-a" >> $GITHUB_ENV
           echo "CXXFLAGS=-march=armv8-a" >> $GITHUB_ENV
+          # Use bundled whisper-rs-sys bindings on macOS
+          echo "WHISPER_DONT_GENERATE_BINDINGS=1" >> $GITHUB_ENV
+          # Clean whisper-rs-sys to ensure it rebuilds with correct env
+          cargo clean -p whisper-rs-sys || true
 
       - name: Check formatting
         run: cargo fmt --all -- --check

.github/workflows/release.yml

@@ -49,6 +49,7 @@ jobs:
           CC=clang CXX=clang++ \
           SDKROOT=$(xcrun --show-sdk-path) \
           MACOSX_DEPLOYMENT_TARGET=13.0 \
+          WHISPER_DONT_GENERATE_BINDINGS=1 \
           cargo build --release --locked --target ${{ matrix.target }} $FEATURES
 
       - name: Create app bundle
@@ -100,6 +101,8 @@ jobs:
         uses: dtolnay/rust-toolchain@stable
 
       - name: Build release binary
+        env:
+          WHISPER_DONT_GENERATE_BINDINGS: "1"
         run: cargo build --release --locked
 
       - name: Strip binary

DEVELOPMENT.md

@@ -88,6 +88,14 @@ cargo build --release --features onnx
 ./build.sh release  # Release
 ```
 
+`build.sh` is a build wrapper for consistent local/release builds across platforms.
+
+- It configures platform-specific build environment before calling Cargo.
+- On Linux, it auto-patches the ELF interpreter when binaries are linked against a Nix loader path, preventing runtime failures like missing `libxcb.so.1` on non-Nix userland.
+- It is recommended for developer and release candidate builds, especially on mixed Nix/system environments.
+
+For production releases, keep using CI per target OS and artifact verification/signing in addition to `build.sh`.
+
 ### GPU Acceleration
 
 OneVox supports GPU acceleration for whisper.cpp backend:
@@ -237,11 +245,13 @@ CC=clang CXX=clang++ SDKROOT=$(xcrun --show-sdk-path) MACOSX_DEPLOYMENT_TARGET=1
   cargo build --release --locked --features onnx
 
 # Linux - Default
-cargo build --release --locked
+./build.sh release
 strip target/release/onevox
 
 # Linux - With ONNX
 cargo build --release --locked --features onnx
+# If built from a Nix shell and run on system userland, patch interpreter:
+# patchelf --set-interpreter /lib64/ld-linux-x86-64.so.2 target/release/onevox
 strip target/release/onevox
 
 # Windows - Default

build.sh

@@ -10,6 +10,39 @@ GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
 NC='\033[0m' # No Color
 
+patch_linux_interpreter() {
+    local binary_path="$1"
+
+    # Only relevant on Linux for ELF binaries.
+    if [ "$(uname -s)" != "Linux" ] || [ ! -f "$binary_path" ]; then
+        return
+    fi
+
+    if ! command -v readelf >/dev/null 2>&1 || ! command -v patchelf >/dev/null 2>&1; then
+        return
+    fi
+
+    local current_interp=""
+    current_interp="$(readelf -l "$binary_path" 2>/dev/null | sed -n 's/.*Requesting program interpreter: \(.*\)]/\1/p' | head -n1)"
+
+    # Nix-linked binaries can fail to resolve transitive system libs outside nix env.
+    if [[ "$current_interp" == /nix/store/* ]]; then
+        local system_interp=""
+        if [ -x /lib64/ld-linux-x86-64.so.2 ]; then
+            system_interp="/lib64/ld-linux-x86-64.so.2"
+        elif [ -x /usr/lib64/ld-linux-x86-64.so.2 ]; then
+            system_interp="/usr/lib64/ld-linux-x86-64.so.2"
+        fi
+
+        if [ -n "$system_interp" ]; then
+            echo -e "${YELLOW}Patching Linux ELF interpreter:${NC} $current_interp -> $system_interp"
+            patchelf --set-interpreter "$system_interp" "$binary_path"
+        else
+            echo -e "${YELLOW}Warning:${NC} binary uses Nix interpreter ($current_interp), but no system ld-linux was found to patch."
+        fi
+    fi
+}
+
 # Detect platform
 OS="$(uname -s)"
 ARCH="$(uname -m)"
@@ -107,6 +140,8 @@ if [ $BUILD_STATUS -eq 0 ]; then
     fi
 
     if [ -f "$BINARY_PATH" ]; then
+        patch_linux_interpreter "$BINARY_PATH"
+
         BINARY_SIZE=$(du -h "$BINARY_PATH" | cut -f1)
         echo "Binary: $BINARY_PATH ($BINARY_SIZE)"
         echo ""

packaging/linux/onevox.service

@@ -13,7 +13,6 @@ StandardError=journal
 
 # Resource limits (optional, can be adjusted per system)
 MemoryMax=2G
-CPUQuota=80%
 
 [Install]
 WantedBy=default.target