# 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 -fLO https://tea.karlcom.de/karl/searchi/releases/download/v0.1.1/searchi-headless_0.1.0_linux-x86_64.tar.xz
curl -fLO https://tea.karlcom.de/karl/searchi/releases/download/v0.1.1/LINUX-SHA256SUMS.txt
sha256sum -c LINUX-SHA256SUMS.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:

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

## 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

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.