Skip to content
Back to search

kaas

Turn scattered notes, docs and transcripts into a queryable Markdown wiki — an LLM knowledge-base compiler with MCP access, no embeddings, self-hosted.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bybit-exchange--kaas/badge.svg)](/listings/bybit-exchange--kaas)

HTML

<a href="/listings/bybit-exchange--kaas"><img src="/api/listings/bybit-exchange--kaas/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

KaaS calls LLMs through any **OpenAI-compatible** API (OpenAI, DeepSeek, Ollama, vLLM, Azure OpenAI, etc.). Pick one of the three paths below.

Option A: Your AI agent

Already living in a coding agent (Claude Code, Codex, openclaw, …)? Give it this repository's URL and ask for what you want — it can do the whole setup. Or paste this to save it a step:

Set up KaaS to build a queryable knowledge base from my files.
Fetch https://raw.githubusercontent.com/bybit-exchange/kaas/main/docs/agent-quickstart.md
and follow it exactly.

> **If you are an AI agent reading this**: fetch > [`docs/agent-quickstart.md`](docs/agent-quickstart.md) and follow that instead of > the shell snippets below. It routes the three things users ask for — build a wiki > from their files, run the full service with the web UI, or point your `ask` tool > at a KaaS that already exists — and marks where to stop and ask them.

That snippet asks for one specific outcome: the AI engine and a queryable wiki, no web UI. Ask your agent for the web UI instead and the runbook sets up the full service — which is the same ground Options B and C cover, written for a human to run by hand.

Option B: Docker

docker run -d --name kaas \
  -p 8080:8080 \
  -v ./data:/app/data \
  -e LLM_API_KEY=sk-xxx \
  -e LLM_BASE_URL=https://api.openai.com/v1 \
  -e LLM_MODEL=gpt-4o-mini \
  ghcr.io/bybit-exchange/kaas:edge

Prebuilt for `linux/amd64` and `linux/arm64`. `edge` tracks `main`. From the first stable release there will also be version tags and `latest` — pin a version for anything you actually depend on. To build from source instead: `docker build -t kaas .`

Option C: CLI install

# Install (Linux amd64/arm64, macOS arm64)
curl -fsSL https://raw.githubusercontent.com/bybit-exchange/kaas/main/install.sh | sh

# Start the service
export PATH="$HOME/.kaas:$PATH"                     # where the installer put the binary
export LLM_API_KEY="sk-xxx"                         # OpenAI-compatible API key
export LLM_BASE_URL="https://api.openai.com/v1"     # API endpoint
export LLM_MODEL="gpt-4o-mini"                      # Model name
kaas serve                                          # Default: http://localhost:8080

Supported platforms: Linux amd64/arm64 and macOS arm64 (Apple Silicon); there is no darwin/amd64 build, so Intel Macs need Option A or B. The binary is symlinked into `~/.kaas`, which the installer will tell you to add to PATH. Uninstall: `rm -rf ~/.local/share/kaas ~/.kaas/kaas`.

After it starts (Options B and C)

`LLM_BASE_URL` defaults to `https://api.openai.com/v1` and `LLM_MODEL` defaults to `gpt-4o-mini`. Change them to point at any OpenAI-compatible endpoint, then open http://localhost:8080.

Running from a checkout instead of a release? See [Development](#development).

Enable remote MCP (optional)

To let Claude Code or other MCP clients connect to the knowledge base, set `KAAS_MCP_ENABLED=true`. Environment variables override `kaas.toml` on every start, so this works for both Docker and `kaas serve`:

docker run -d --name kaas \
  -p 8080:8080 \
  -v ./data:/app/data \
  -e LLM_API_KEY=sk-xxx \
  -e KAAS_MCP_ENABLED=true \
  -e KAAS_MCP_TOKEN=your-secret-token \
  ghcr.io/bybit-exchange/kaas:edge

MCP client URL: `http://<host>:8080/mcp`, Authorization: `Bearer your-secret-token`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 324 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <img src="docs/assets/logo.svg" align="right" width="110" alt="KaaS — Knowledge-as-a-Service">
  2. # KaaS — Knowledge as a Service
  3. **English** · [中文](README.zh-CN.md)
  4. [![Tests](https://github.com/bybit-exchange/kaas/actions/workflows/tests.yml/badge.svg)](https://github.com/bybit-exchange/kaas/actions/workflows/tests.yml)
  5. [![License](https://img.shields.io/github/license/bybit-exchange/kaas?color=blue)](LICENSE)
  6. [![Latest release](https://img.shields.io/github/v/release/bybit-exchange/kaas?include_prereleases)](https://github.com/bybit-exchange/kaas/releases)
  7. [![Documentation](https://img.shields.io/badge/docs-kaas--doc-blue)](https://bybit-exchange.github.io/kaas-doc/)
  8. [![MCP](https://img.shields.io/badge/MCP-ask%20tool-black)](#mcp-access)
  9. Turn scattered notes, documents, and transcripts into a searchable, queryable personal Wiki — powered by LLM-driven knowledge compilation.
  10. **[Documentation](https://bybit-exchange.github.io/kaas-doc/)** · [Quick Start](#quick-start) · [MCP access](#mcp-access)
  11. ![Asking the compiled wiki a question and getting an answer with citations back to the articles it came from](docs/assets/screenshot-chat.en.png)
  12. ## What Makes This Different
  13. Unlike typical RAG systems that chunk and embed raw text, KaaS **compiles** your
  14. content through a 4-phase LLM pipeline. What comes out is human-readable Markdown
  15. articles — not a black-box vector store.
  16. ![KaaS vs. naive RAG: compile-then-retrieve instead of chunk-and-embed](docs/assets/kaas-vs-rag.en.svg)
  17. ## The Compiled Wiki
  18. What you get is a tree of Markdown articles: categories on the left, the rendered
  19. article in the middle, its headings down the right. Chat answers cite these
  20. articles by name, so an answer and the page it came from are one click apart.
  21. ![The compiled wiki: an article tree on the left, a rendered Markdown article on the right](docs/assets/screenshot-wiki.en.png)
  22. ## How It Works
  23. Raw content passes through four LLM phases: extract concepts, entities and
  24. decisions; classify them into articles; write or merge the Markdown; update the
  25. indexes. Retrieval then reads whole pages rather than embedded fragments — the
  26. LLM walks the master index, picks the articles it needs, and answers from their
  27. full text.
  28. ![KaaS: distill your notes into a structured, readable wiki, then retrieve](docs/assets/distill-flow.en.svg)
  29. ## Why We Built This
  30. KaaS started as an internal tool. Our knowledge lived scattered across
  31. documents, meetings, and email — and every time someone changed roles or left,
  32. the context they'd built up walked out with them. New people spent weeks
  33. piecing it back together.
  34. A distillation pipeline fixed that. It compiles each person's scattered
  35. material into a wiki tied to their _role_ rather than their identity — so when
  36. someone moves on, the raw data goes but the distilled judgment stays for whoever
  37. fills the seat next.
  38. The payoff is the same either way: the organization stops re-answering the same
  39. questions. That's what convinced us it was worth open-sourcing.
  40. ## Quick Start
  41. KaaS calls LLMs through any **OpenAI-compatible** API (OpenAI, DeepSeek, Ollama, vLLM, Azure OpenAI, etc.). Pick one of the three paths below.
  42. ### Option A: Your AI agent
  43. Already living in a coding agent (Claude Code, Codex, openclaw, …)? Give it this
  44. repository's URL and ask for what you want — it can do the whole setup. Or paste
  45. this to save it a step:
  46. ```
  47. Set up KaaS to build a queryable knowledge base from my files.
  48. Fetch https://raw.githubusercontent.com/bybit-exchange/kaas/main/docs/agent-quickstart.md
  49. and follow it exactly.
  50. ```
  51. > **If you are an AI agent reading this**: fetch
  52. > [`docs/agent-quickstart.md`](docs/agent-quickstart.md) and follow that instead of
  53. > the shell snippets below. It routes the three things users ask for — build a wiki
  54. > from their files, run the full service with the web UI, or point your `ask` tool
  55. > at a KaaS that already exists — and marks where to stop and ask them.
  56. That snippet asks for one specific outcome: the AI engine and a queryable wiki, no
  57. web UI. Ask your agent for the web UI instead and the runbook sets up the full
  58. service — which is the same ground Options B and C cover, written for a human to
  59. run by hand.
  60. ### Option B: Docker
  61. ```bash
  62. docker run -d --name kaas \
  63. -p 8080:8080 \
  64. -v ./data:/app/data \
  65. -e LLM_API_KEY=sk-xxx \
  66. -e LLM_BASE_URL=https://api.openai.com/v1 \
  67. -e LLM_MODEL=gpt-4o-mini \
  68. ghcr.io/bybit-exchange/kaas:edge
  69. ```
  70. Prebuilt for `linux/amd64` and `linux/arm64`. `edge` tracks `main`. From the
  71. first stable release there will also be version tags and `latest` — pin a
  72. version for anything you actually depend on. To build from source instead:
  73. `docker build -t kaas .`
  74. ### Option C: CLI install
  75. ```bash
  76. # Install (Linux amd64/arm64, macOS arm64)
  77. curl -fsSL https://raw.githubusercontent.com/bybit-exchange/kaas/main/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 108 on GitHub
  78. # Start the service
  79. export PATH="$HOME/.kaas:$PATH" # where the installer put the binary
  80. export LLM_API_KEY="sk-xxx" # OpenAI-compatible API key
  81. export LLM_BASE_URL="https://api.openai.com/v1" # API endpoint
  82. export LLM_MODEL="gpt-4o-mini" # Model name
  83. kaas serve # Default: http://localhost:8080
  84. ```
  85. Supported platforms: Linux amd64/arm64 and macOS arm64 (Apple Silicon); there is
  86. no darwin/amd64 build, so Intel Macs need Option A or B. The binary is symlinked into
  87. `~/.kaas`, which the installer will tell you to add to PATH. Uninstall:
  88. `rm -rf ~/.local/share/kaas ~/.kaas/kaas`.
  89. ### After it starts (Options B and C)
  90. `LLM_BASE_URL` defaults to `https://api.openai.com/v1` and `LLM_MODEL` defaults to
  91. `gpt-4o-mini`. Change them to point at any OpenAI-compatible endpoint, then open
  92. http://localhost:8080.
  93. Running from a checkout instead of a release? See [Development](#development).
  94. ### Enable remote MCP (optional)
  95. To let Claude Code or other MCP clients connect to the knowledge base, set
  96. `KAAS_MCP_ENABLED=true`. Environment variables override `kaas.toml` on every
  97. start, so this works for both Docker and `kaas serve`:
  98. ```bash
  99. docker run -d --name kaas \
  100. -p 8080:8080 \
  101. -v ./data:/app/data \
  102. -e LLM_API_KEY=sk-xxx \
  103. -e KAAS_MCP_ENABLED=true \
  104. -e KAAS_MCP_TOKEN=your-secret-token \
  105. ghcr.io/bybit-exchange/kaas:edge
  106. ```
  107. MCP client URL: `http://<host>:8080/mcp`, Authorization: `Bearer your-secret-token`.
  108. ## Architecture
  109. ![Architecture](docs/assets/architecture.en.svg)
  110. | Layer | Tech | Purpose |
  111. |-------|------|---------|
  112. | Web UI | React + Vite + shadcn/ui | Chat, Submit, Wiki, Status |
  113. | Backend | Go (net/http + go-zero/conf) | REST API, Worker Pool, Task Queue, MCP endpoint |
  114. | AI Engine | Python (kb-ai daemon) | LLM Compile Pipeline, LLM-iterative retrieval, Chat |
  115. | Storage | SQLite (default) / MySQL | Job queue, compile state |
  116. | Retrieval | LLM iterative | master-index → LLM page selection → full-article context (no embeddings) |
  117. The Go backend spawns the Python AI engine as a long-running daemon process, communicating via a multiplexed stdin/stdout protocol. A single Docker image bundles everything — no sidecar containers needed.
  118. ## Features
  119. - **Readable articles**: what you query is pages, not ranked fragments — see [How It Works](#how-it-works) for the four phases that produce them
  120. - **Answers you can check**: every chat reply cites the wiki articles behind it, so you can open the source and disagree with it (streamed over SSE)
  121. - **A knowledge base you own**: articles are plain Markdown on disk — read them, hand-edit them, commit them, review a diff
  122. - **Adding one document costs one document**: compiles are incremental against a content checksum, so a new note doesn't re-pay for the corpus you already compiled
  123. - **A long run survives its own failures**: extract and pipeline work runs concurrently; tasks are leased, so a worker that dies mid-compile has its work reclaimed rather than lost, and repeated LLM failures trip a breaker instead of burning spend
  124. - **Text, a file, or a URL**: paste it, upload it, or point KaaS at a page
  125. - **Reachable from your editor**: any MCP-capable coding agent queries the compiled wiki through a single `ask` tool
  126. ## MCP Access
  127. Expose the compiled wiki to any [Model Context Protocol](https://modelcontextprotocol.io)
  128. client (Claude Code, Codex, openclaw, …) through a single `ask` tool —
  129. `ask(query, paths?, model?)` returns a cited Markdown answer grounded in the
  130. wiki. Two transports:
  131. **stdio** (local — the agent spawns the server, fully self-contained):
  132. ```bash
  133. # The agent launches this; set KAAS_KB_DIR to the knowledge-base root and
  134. # the LLM_* credentials in the environment.
  135. kb-ai mcp # stdio is the default transport
  136. ```
  137. ```bash
  138. # Claude Code:
  139. claude mcp add kaas -- kb-ai mcp
  140. ```
  141. For Codex / openclaw, add a stdio MCP server with command `kb-ai mcp` and env
  142. `KAAS_KB_DIR` + `LLM_*`.
  143. **streamable-http** (remote — published through the backend's `:8080` origin):
  144. Run the container with `KAAS_MCP_ENABLED=true` (see [Quick Start](#quick-start)).
  145. The backend exposes the MCP endpoint at `/mcp`. Point a remote agent at it:
  146. ```bash
  147. # Claude Code:
  148. claude mcp add --transport http kaas http://host:8080/mcp
  149. ```
  150. Set `KAAS_MCP_TOKEN` to require `Authorization: Bearer <token>` on the HTTP
  151. transport (off by default — local/intranet assumption). stdio has no network
  152. surface and is unauthenticated.
  153. ## Configuration
  154. All configuration lives in `etc/kaas.toml`. Copy and edit it:
  155. ```toml
  156. [llm]
  157. api_key = "sk-..."
  158. base_url = "https://api.openai.com/v1"
  159. model = "gpt-4o-mini"
  160. [ai.mcp]
  161. enabled = false # set true to expose /mcp endpoint
  162. token = "" # bearer token for MCP auth (empty = no auth)
  163. timeout_sec = 120 # tools/call timeout
  164. ```
  165. With Docker or the CLI, pass secrets as environment variables — they override the
  166. TOML at startup:
  167. | Env Var | Overrides | Default |
  168. |---------|-----------|---------|
  169. | `LLM_API_KEY` | `[llm] api_key` | _(empty)_ |
  170. | `LLM_BASE_URL` | `[llm] base_url` | `https://api.openai.com/v1` |
  171. | `LLM_MODEL` | `[llm] model` | `gpt-4o-mini` |
  172. | `LLM_SUMMARIZE_MODEL` | `[llm] summarize_model` | same as `model` |
  173. | `KAAS_MCP_ENABLED` | `[ai.mcp] enabled` | `false` |
  174. | `KAAS_MCP_TOKEN` | `[ai.mcp] token` | _(empty = no auth)_ |
  175. | `KAAS_WEB_DIR` | `[server] web_dir` | `/app/web/dist` (in Docker) |
  176. | `KAAS_AI_MCP_URL` | `[ai] mcp_url` | _(deprecated — use `KAAS_MCP_ENABLED`)_ |
  177. | `KB_AI_WRITE_TIMEOUT_S` | _(env only)_ | `300` |
  178. | `KB_AI_EXTRACT_TIMEOUT_S` | _(env only)_ | `180` |
  179. Raise `KB_AI_WRITE_TIMEOUT_S` when compiling with a slow local model. A write call
  180. rewrites a whole article, so its latency tracks the article's length rather than the
  181. prompt's: merging nine documents into one article on a local 27B model took 349s,
  182. past the 300s default, and a call that runs out of budget surfaces as a per-document
  183. entry in the run's `errors` rather than as a failed command.
  184. There is no single right value, because local throughput is not a property of the
  185. model alone. The same call on the same machine took 349s with one model resident and
  186. over 900s with a second model sharing the GPU. Size it from the slowest write you
  187. actually observe, and note the budget is per attempt — a timeout is retried twice,
  188. so the wall-clock cost of a value that is still too low is three times over.
  189. `KB_AI_EXTRACT_TIMEOUT_S` is the same knob for the extract phase, and the phase that
  190. usually needs it first: extract runs on every document, so it is where a slow model
  191. fails earliest. Its 180s default is deliberately tighter than the write phase's,
  192. because extract calls are bounded in size and a single hung one blocks the whole job
  193. — but that figure assumes a hosted model's generation speed. A local 12B model
  194. exhausted all three attempts on a 4386-character prompt, which is a small document.
  195. Size extract more conservatively than the write phase, because it retries in two
  196. places rather than one: the LLM layer retries a timeout twice, and the summarize
  197. strategy's second phase re-dispatches its entire call set once on any failure. A
  198. hung call there costs six attempts to discover — about 1140s at the 180s default,
  199. and over 90 minutes at 900s — so a value that is still too low is expensive twice
  200. over.
  201. Both variables ignore an unusable value (zero, negative, non-numeric, NaN, or
  202. infinite) and say so once on stderr, rather than letting a typo in an env var decide
  203. how a compile behaves.
  204. The docs site has a
  205. [full configuration reference](https://bybit-exchange.github.io/kaas-doc/getting-started/configuration.html)
  206. covering the settings not listed here.
  207. ## Development
  208. The quickest way to start all services locally:
  209. ```bash
  210. # First time: create your local config (not tracked by git)
  211. cp etc/kaas.toml etc/kaas-dev.toml
  212. # Edit etc/kaas-dev.toml — set your LLM credentials:
  213. # [llm]
  214. # api_key = "sk-..."
  215. # base_url = "https://api.openai.com/v1" # or your preferred endpoint
  216. # model = "gpt-4o-mini"
  217. make dev
  218. ```
  219. This launches the Go backend (which auto-spawns the Python AI daemon) and the Vite dev server together.
  220. To run components individually:
  221. ```bash
  222. # Backend (spawns Python daemon automatically)
  223. go run ./cmd/kaas -f etc/kaas.toml
  224. # Frontend (hot-reload)
  225. cd web && pnpm dev
  226. # MCP server (stdio — for local agent integration)
  227. cd py && KAAS_KB_DIR=./data uv run kb-ai mcp
  228. # Tests
  229. make test
  230. ```
  231. ## Contributing
  232. Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup,
  233. how to run the tests, and commit conventions.
  234. ## Acknowledgments
  235. The core idea — compiling knowledge into a persistent, interlinked wiki that
  236. compounds over time instead of re-deriving answers via RAG on each query — was
  237. inspired by Andrej Karpathy's ["LLM Wiki"](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
  238. gist. Thanks for the clear articulation of the pattern.
  239. ## License
  240. MIT — see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.