searchi/docs/LINUX-HEADLESS.md

searchi on a Linux server

Use the headless version to search your local files from a terminal or connect an AI agent through read-only MCP. It includes the Google EmbeddingGemma 2 worker, automatic CPU/GPU selection with CPU fallback, and FFmpeg helpers. There is no desktop shell in this package.

Install and prepare search

This initial x86-64 preview was checked on Ubuntu 24.04 in WSL. It requires GLIBC 2.39, GLIBCXX 3.4.32 and CXXABI 1.3.13 or compatible newer runtime versions. Older Linux distributions should build from source; this archive is not an all-distribution compatibility claim.

Download into a new dedicated directory and verify before extracting:

mkdir -p "$HOME/Applications/searchi"
cd "$HOME/Applications/searchi"
curl -fLO https://tea.karlcom.de/karl/searchi/releases/download/v0.1.3/searchi-headless_0.1.0_linux-x86_64-013.tar.xz
curl -fLO https://tea.karlcom.de/karl/searchi/releases/download/v0.1.3/LINUX-SHA256SUMS-0.1.3.txt
sha256sum -c LINUX-SHA256SUMS-0.1.3.txt
tar -xf searchi-headless_0.1.0_linux-x86_64.tar.xz
./searchi --help
./searchi setup --model-dir ./models

The package is approximately 103 MB. First model setup downloads approximately 865 MB and reuses verified cached assets. Keep the runtime libraries and media helpers alongside the CLI. To use graphics acceleration, the system needs a compatible Vulkan loader and graphics driver; otherwise search uses CPU.

Choose your own folder by replacing /path/to/your/files below:

./searchi index --db ./searchi.sqlite --root /path/to/your/files
./searchi embed --db ./searchi.sqlite --model-dir ./models --embedding-worker ./searchi-gemma-worker
./searchi search --db ./searchi.sqlite 'what you remember' --model-dir ./models --embedding-worker ./searchi-gemma-worker

Indexing names/content and embedding meaning are separate CLI steps. After changing files, run both again to refresh their local index. Add --code-only to search source implementations. For filenames/content without model inference, omit both model arguments. --json --performance reports basic measurements; --debug-performance enables detailed traces.

Connect your local agent

Configure a stdio MCP client to run the absolute path to searchi, with these arguments using absolute paths:

mcp --db /absolute/path/searchi.sqlite --model-dir /absolute/path/models --embedding-worker /absolute/path/searchi-gemma-worker

MCP searches the prepared index and reads only its cited excerpts. It does not index or mutate files. See agent integration.

Recorded package evidence, 2026-10-13

Headless component version 0.1.0 is supplied alongside desktop release 0.1.1. All 89 selected engine/CLI and workspace lock/manifest files matched current Git archive bytes before a locked offline native release rebuild. Runtime source and recipe bytes were also compared; current worker SHA-256: b52d50a1e676bd4bf64124daff1c4ce83d86a8bde01e4eaf09838cbb24a4c28f. CLI SHA-256: 0a169112aab66f6b80d3696e6eb06bbd2a8ab8d1a845956353c897ab36691cdb.

Sixteen packaging tests passed in normal and optimized Python modes, including XZ member/checksum/mode equality and reproducibility. Actual extracted archive checks verified 29 files, relocated paths containing spaces, automatic media helper discovery, three newly encoded Google chunks (two documents plus one audio), German semantic document search, Code-scope source citation and strict extension filtering. A separate genuine CPU MCP preflight passed with this worker. No GPU provider was exercised.

Archive: 103,295,132 bytes, SHA-256 940c1f871a8775723fc571018fd2f9f946f48528dac3fdea0888a3d90cacc8a6. Public unauthenticated full-byte archive and checksum downloads matched local files. Ignored final report .searchi/qa/linux-xz-current-runtime-smoke.json, SHA-256 35d4795469e6c22f778218161a97d160a3148a3a30a55435ef0c7f775601846b.

An earlier candidate used a historical staged worker and failed query startup with Unknown worker option. It was never published. The old archive remains locally as searchi-headless-legacy-worker.tar.xz; captured failure evidence is .searchi/qa/linux-xz-release-diagnostic.json. The corrected package uses the current runtime and passed the same full archive check.

WSL CPU deployment proof does not establish broad distribution compatibility, clean-machine installs, real GPU fallback/parity, Linux desktop behavior or general media relevance. Those checks remain open.

Updated archive alongside Windows 0.1.3

Shared component version remains 0.1.0. Source 9ce6099 was rebuilt on Ubuntu WSL; the archive now includes the required extraction helper. All 31 recorded file hashes/sizes matched; relocated normal CLI indexing extracted PDF page 1 and DOCX paragraph 1 with zero failures. Genuine Google CPU inference encoded two chunks and semantic search returned both documents with their locations. This is a two-document smoke check, not a general relevance benchmark.

Archive: 104201084 bytes, SHA-256 4daf58a5fd6f538f72a1aef9b2f58f3cad0ef9a6bdc69f649b98b6a09ffa029b. Public full-byte archive and checksum downloads matched. GPU and broader distribution tests remain open. Earlier evidence above describes the old archive.