Get started

1. Download and unzip

The standalone zip is a small runnable project: Dockerfile, starter config/, SQLite demo data, and a copy of planning/ (schemas + protocol docs so you or an LLM can author real YAML). Unzip anywhere; you do not need the full Git history.

2. Configure for your sources

Before you treat the stack as “yours”, read Configure — preset, catalog, REST itemsKey / fromFilter, runtime config, and env.

Everything under config/ in the zip (and deploy/ in the full monorepo) is an example of file shape only. Replace hosts, env var names, entities, and fields with your real sources. The included SQLite items table is a smoke demo, not a template to keep in production.

When asking an LLM to write config, point it at the local planning/ folder in the zip (especially planning/schemas/). planning/ wins over any guessed API shape.

3. Docker

cp .env.example .env   # set QLLM_AUTH_TOKEN
docker build -t qllm-standalone .
docker run --rm -p 8088:8088 -p 8089:8089 --env-file .env qllm-standalone

Defaults: HTTP on 8088, MCP HTTP on 8089. After you replace the example YAML, rebuild or mount ./config over /config.

4. Health and catalog

curl -s http://127.0.0.1:8088/v1/health
curl -s -H "Authorization: Bearer change-me" http://127.0.0.1:8088/v1/catalog

Replace change-me with the token from your .env. Health stays unauthenticated for probes; catalog and queries require Bearer when auth is configured.

Example stack (qLLM in action)

Want a full story, not just a zip? jpandrade30/SmallDemo (Northline) runs a fictional company on Rancher Desktop / k3s: siloed ERP and services, approval console, GitOps (Gitea + Argo CD), and qLLM over HTTP + MCP for the agent chat.

When to clone vs zip

Develop from a full clone

go build -o qllm ./cmd/qllm
./qllm validate --config-dir ./my-project
./qllm serve --http --config-dir ./my-project

Without YAML in --config-dir (or CWD), serve fails with CONFIG_ERROR. Field-by-field install notes: docs/en/install.md.