From 5c50d3131ec56ef288d375bcf6fe55f65be1fb8d Mon Sep 17 00:00:00 2001 From: Alex Clarke Date: Fri, 28 Aug 2026 22:33:30 -0600 Subject: [PATCH] docs: Added the linux GNU vs MUSL differentiation for DuckDB RAG drivers --- Agents.md | 4 ++++ Graph-Agents.md | 3 ++- Installation.md | 8 ++++++++ RAG.md | 11 ++++++++++- 4 files changed, 24 insertions(+), 2 deletions(-) diff --git a/Agents.md b/Agents.md index 000c3fb..90f5afd 100644 --- a/Agents.md +++ b/Agents.md @@ -319,6 +319,10 @@ The first time an agent starts with documents attached, Coyote offers to build t start. The choice is fixed once the knowledge base is built: changing it means removing the agent's built knowledge base and letting it rebuild, which re-embeds every document. +> [!NOTE] +> On Linux, `duckdb` requires a gnu build. Musl builds are statically linked and cannot load DuckDB's +> extensions, so they skip the prompt and use `yaml` ([details](RAG#duckdb)). + When function calling is enabled, an agent with `documents` also gets the [`rag__query`](RAG#runtime-retrieval) built-in tool, which lets the LLM run additional retrieval on-demand during a turn (in addition to the up-front injection). [Graph agents](Graph-Agents) drive RAG through explicit `rag` nodes instead and do not receive this tool. diff --git a/Graph-Agents.md b/Graph-Agents.md index 9e6b82a..ffcfcad 100644 --- a/Graph-Agents.md +++ b/Graph-Agents.md @@ -633,7 +633,8 @@ base is first built): Falls back to `rag_graph_hops`. Higher values surface more loosely related documents; keep at `1` for most corpora. - **`batch_size`:** Embedding-request batch size. - **`driver`:** [Storage driver](RAG#storage-drivers) for this node's knowledge base. Can be `yaml` - (default) or `duckdb`. Use `duckdb` when the node's corpus is large enough that rebuilding + (default) or `duckdb` (Note that musl Linux builds cannot load DuckDB's extensions and + always use `yaml`). Use `duckdb` when the node's corpus is large enough that rebuilding the in-memory index on every agent start is noticeable; it keeps vectors and text on disk in a `.duckdb` file beside the generated knowledge base. An invalid driver is rejected when the graph is validated, naming the offending node. Like every field in this diff --git a/Installation.md b/Installation.md index b72ed29..d9f2e6e 100644 --- a/Installation.md +++ b/Installation.md @@ -102,6 +102,14 @@ Binaries are available on the [releases](https://github.com/Dark-Alex-17/coyote/ | Linux GNU/MUSL | x86_64, aarch64 | | Windows | x86_64, aarch64 | +#### Linux: GNU or MUSL? +The MUSL binaries are fully static and run on any distribution. That same static linking, though, means they cannot +load DuckDB's extensions, so the [duckdb RAG driver](RAG#duckdb) is unavailable in them. The GNU binary supports +duckdb; it needs a recent glibc and OpenSSL 3 (`libssl.so.3`). The install script checks for both, verifies that the +downloaded binary actually runs on your system, and falls back to MUSL when the GNU build isn't viable. So taking +the script's choice is safe. `coyote --update` keeps whichever flavor is already installed. ARM Linux currently +ships MUSL only, so duckdb is unavailable there for now. + ### Windows Instructions To use a binary from the releases page on Windows, do the following: diff --git a/RAG.md b/RAG.md index bc6f565..234575a 100644 --- a/RAG.md +++ b/RAG.md @@ -172,6 +172,11 @@ Coyote asks which one you want whenever it builds a knowledge base interactively If you don't care, take the default. `yaml` is what Coyote has always done. +> [!NOTE] +> On Linux **musl** builds the prompt is skipped entirely: the duckdb driver needs a **gnu** build (musl binaries are +> statically linked, and a static binary cannot load DuckDB's `vss`/`fts` extensions), so Coyote notes as much and uses +> `yaml`. See [Installation](Installation#linux-gnu-or-musl) for which flavor you have and how to switch. + > **A RAG's driver is fixed when it's created.** There is no conversion step. Switching means deleting the RAG and > building it again, which re-embeds every document. Worth a moment's thought before you pick, but not worth agonizing > over: for small corpora the difference is not something you'll notice. @@ -187,8 +192,12 @@ simultaneously. Its cost is startup: a large corpus means a large file to parse Vectors, document text and the search indexes live in a `.duckdb` file next to the RAG, and stay there between runs. Nothing is rebuilt at startup, so loading a large RAG is quick regardless of size. -Two things are worth knowing before you choose it: +Three things are worth knowing before you choose it: +* **Linux needs the gnu build.** Coyote's musl binaries are statically linked, and a static binary cannot load + DuckDB's extensions, so the duckdb driver is unavailable there: the wizard doesn't offer it, and a configuration + that names it fails with an explanation. The [install script](Installation#linux-gnu-or-musl) prefers the gnu + build automatically on x86_64 glibc systems; ARM Linux ships musl only, so duckdb is currently unavailable there. * **Concurrency is readers-or-writer.** Several Coyote processes can query the same duckdb RAG at once. While one process is *ingesting* or *rebuilding* it, though, the others can't read it until that finishes. If you routinely run several Coyotes against one RAG and rebuild it often, `yaml` will annoy you less.