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:

```sh
mkdir -p "$HOME/Applications/searchi"
cd "$HOME/Applications/searchi"
curl -A "Mozilla/5.0" -fLO https://tea.karlcom.de/karl/searchi/releases/download/v0.1.7/searchi-headless_0.1.6_linux-x86_64.tar.xz
curl -A "Mozilla/5.0" -fLO https://tea.karlcom.de/karl/searchi/releases/download/v0.1.7/searchi-headless_0.1.6_linux-x86_64.tar.xz.sha256
sha256sum -c searchi-headless_0.1.6_linux-x86_64.tar.xz.sha256
tar -xf searchi-headless_0.1.6_linux-x86_64.tar.xz
./searchi --help
./searchi setup --model-dir ./models
```

The package is approximately 109 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:

```sh
./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.

### Search spoken passages

Version 0.1.6 includes experimental local speech search. Download the additional
recognition assets (about 149 MB), then encode recognized passages alongside
Google's media embeddings:

```sh
./searchi setup --speech --model-dir ./speech-models
./searchi embed --db ./searchi.sqlite --model-dir ./models --embedding-worker ./searchi-gemma-worker --speech-worker ./speech-runtime/searchi-speech-worker --speech-model-dir ./speech-models
```

Use the same `search` command above. Spoken passages include estimated timestamps;
recognition can miss words, and results can be irrelevant when no matching content
exists. After changing files, repeat `index` and this speech-enabled `embed` command.

## Connect your local agent

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

```text
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](AGENT-INTEGRATION.md).

## Recorded package evidence, 2026-10-13

Current package: [Linux headless 0.1.6](LINUX-SPEECH-0.1.6.md), including genuine
packaged Google/speech CPU retrieval and public download verification. The
following records retain older release evidence.

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.