Skald: a self-hosted RAG API with configurable retrieval and an enterprise carve-out

The gap Skald fills between a vector store and a working RAG service

A vector database gives you similarity search. It does not parse your PDFs, decide how to split them, summarise them, tag them, embed them, rewrite the user's query, call a model, keep chat history, and hand back citations. Teams that build RAG usually write that glue themselves, and the glue is where the schedule goes. Skald's pitch is that the glue is the product: the README describes an ingestion phase covering document parsing, chunking strategy, summaries, tagging, embedding generation and vector storage, and a retrieval phase covering query rewriting, vector search, LLM chat, chat history and source references. The intended user is a backend team that wants a knowledge chat feature without owning a retrieval pipeline. The README frames the entry point as a plug-and-play API, with defaults that the project claims will work for most use cases and configuration available where they do not.

Ingestion and retrieval as two named phases

The architecture is clearest in the README's own split. Everything before a query is ingestion: a document goes in, and the service handles parsing, a chunking strategy, summaries, tags, embeddings and the vector store write. Everything after a query is retrieval: the query is rewritten, a vector search runs, an LLM produces the chat response, history is maintained, and source references come back with the answer. That is a conventional RAG data flow, and Skald's contribution is that the stages are named, individually configurable, and reachable through one API rather than being steps in a script you maintain. The configuration surface named in the README includes vector search parameters, reranking, models, and query rewriting, with chunking listed as coming soon. That last item matters: the README says chunking is configurable in the future tense, so at the time of writing the chunking strategy is something Skald applies rather than something you tune. If chunk boundaries are a live concern for your documents, that is a current limit, not a setting.

Getting a local instance up, and the env var it expects

The README's try-it block is four commands. Clone the repository, change into it, write an .env file containing OPENAI_API_KEY, and run docker-compose up. The literal sequence given is:

git clone https://github.com/skaldlabs/skald cd skald echo "OPENAI_API_KEY=<your_key>" > .env docker-compose up

That is the whole quickstart. The single environment variable named in the README is OPENAI_API_KEY, which tells you what the default path assumes: a hosted model provider for the chat and embedding work. The README also documents a way out. A collapsed section titled running Skald without any third-party services states that you can deploy without third-party dependencies including OpenAI, but that this requires hosting your own LLM inference server and using a local embeddings service, and that the project provides one in the local docker compose profile. The README labels this advanced usage and points to the docs. So there are two deployment shapes: a fast one that depends on a hosted provider, and a self-contained one that costs you an inference server. The self-hosting docs are linked separately for production deploys with SSL, and the README claims that can be live in less than an hour.

The SDK call shape and what rag_config controls

The Node example in the README is short enough to read as the whole contract. You construct a client with an API key, call createMemo with a title and content, then call chat with a query and a rag_config object. The example passes rag_config: { reranking: { enabled: true } }, and logs chatRes.response. Two things follow from that. First, ingestion is a single call per document, with title and content as the fields shown, so whatever parsing and chunking happens is server-side and not something the caller orchestrates. Second, retrieval tuning is per-request: reranking is toggled inside the chat call rather than configured once at the server. That is a real design choice with a real consequence. You can A/B reranking from application code without redeploying the service, but every caller now carries responsibility for the config, and inconsistent configs across callers produce inconsistent answer quality. The README names SDKs for Node, Python, Ruby, Go, PHP, C#, plus an MCP server and a CLI, with versions listed in the badge block. The Python package is skald-sdk on PyPI, the Node package is @skald-labs/skald-node, and the CLI is @skald-labs/cli.

The licence is split, and the ee directory is the seam

The repository metadata reports the licence as NOASSERTION, and the README explains why: the repo is MIT except for the ee directory, which has its own licence file. The README states plainly that if you need 100% FOSS code you can use the skald-foss repository, which is this repo with ee removed, that skald-foss is fully featured, and that the vendor runs skald-foss on its own Cloud offering. It also says the Enterprise Edition is meant for on-prem deployments. That is an unusually candid arrangement and it is worth reading literally. The MIT grant covers the bulk of the tree; the ee directory is governed by a separate file you should open before deploying, because the difference between the two repositories is exactly the code you would be running. Nothing here is legal advice, and the practical step is narrow: read ee/LICENSE in the commit you intend to ship, and if its terms do not suit you, use skald-foss instead of stripping directories yourself.

Where Skald is the wrong tool

Skald is a service, not a library, and that shapes when it does not fit. If your retrieval logic is the differentiator, for example a custom ranking function over domain-specific signals, you will be configuring around a pipeline whose stages are fixed by the server, and the README lists chunking as not yet configurable. If you need a fully offline deployment, the README is explicit that this requires hosting your own inference server and a local embeddings service, calls it advanced usage, and defers to the docs; the four-command quickstart does not get you there. If you are unwilling to run additional infrastructure, the cloud option exists but the point of the project is running it yourself. And if you want to evaluate retrieval quality before you have data in the system, note that the README lists built-in evaluation tools as a feature, but the material available here gives no example, no command and no metric, so treat evaluation as something to verify in the docs rather than something you can plan around today.

What you would otherwise assemble, and how the approaches differ

The obvious alternative is composing the pipeline yourself from parts: a parser such as an unstructured-document loader, a chunker, an embedding model, a vector store, and a model client, wired together in your own service. The difference is not capability, it is where the decisions live. In a hand-built pipeline, chunk size, embedding model, reranking and query rewriting are code you own and can change per document type, and the retrieval path is inspectable at every step. In Skald, those decisions are server configuration and per-request parameters, which buys you a working endpoint quickly and costs you the ability to reach inside a stage that has not been exposed yet. A second alternative is a managed RAG offering, where the trade is the opposite: less operational work, but your documents and queries leave your infrastructure, which is precisely what the project's description, a context layer platform in your infrastructure, is positioned against. Skald sits between those two, and the honest summary is that it wins on time-to-first-answer and loses on depth of control.

Maintenance surface, upgrade path and what has no release history here

The repository is not archived and the last push recorded is 2026-05-31, so the project is active. No releases were retrieved, which means there is no changelog in this material to tell you how upgrades behave or whether breaking changes are batched. What you can see is a version spread across the client packages: Python at 0.4.1, Node at 0.4.0, Go at 0.3.0, Ruby at 0.1.0, PHP at 1.0.2, C# at 0.1.0, MCP at 0.1.0, CLI at 0.1.3. Those are client versions, not server versions, and the gap between Ruby at 0.1.0 and PHP at 1.0.2 suggests the SDKs are not maintained in lockstep. If you depend on a non-Node SDK, pin the version and read that SDK's own repository, since the README links each one separately. The maintenance cost you are actually taking on is the inference server if you go the no-third-party route, plus the upgrade risk of a young API surface with no published release notes to read first.

Editorial conclusion

Adopt Skald if you want a RAG service you can run inside your own infrastructure and call over HTTP, with SDKs already written for the languages your team uses, and if you accept that the default path assumes a hosted model provider. Do not adopt it if you need a fully offline deployment out of the box, or if you cannot tolerate the ee directory sitting under a separate licence from the rest of the repository. Before committing, verify three things: what the ee directory actually contains in the commit you plan to deploy, whether the local docker compose profile gives you the embeddings and inference path you need, and whether the query rewriting and reranking defaults are acceptable for your data. The skald-foss repository removes the ee directory entirely and, per the README, is what the vendor runs on its own Cloud offering.

Official sources

1. Issues
2. Project website
3. README
4. skaldlabs/skald on GitHub