Installation

KaaS offers three installation paths. Pick the one that fits your workflow:

Path	Best For	Requirements
Docker	Production or hands-off setup	Docker
CLI	Running directly on a host	Linux/macOS, amd64/arm64
Agent-First	Users already in Claude Code / Codex	A coding agent + Python (uv/pipx/pip)

All paths require an OpenAI-compatible API key (OpenAI, DeepSeek, Ollama, vLLM, Azure, etc.).

---

Option A: Docker (Recommended)

1. Build the Image

docker build -t kaas https://github.com/bybit-exchange/kaas.git

Or clone and build locally:

git clone https://github.com/bybit-exchange/kaas.git
cd kaas
docker build -t kaas .

2. Run the Container

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 \
  kaas

Parameters explained:

Flag	Purpose
-p 8080:8080	Map container port 8080 to host
-v ./data:/app/data	Persist wiki data and SQLite database
-e LLM_API_KEY	Your OpenAI-compatible API key
-e LLM_BASE_URL	API endpoint (default: https://api.openai.com/v1)
-e LLM_MODEL	Model name (default: gpt-4o-mini)

Defaults

LLM_BASE_URL defaults to https://api.openai.com/v1 and LLM_MODEL defaults to gpt-4o-mini. You only need to set them explicitly for a non-OpenAI provider.

3. Enable MCP (Optional)

To let Claude Code or other MCP clients query the knowledge base remotely:

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 \
  -e KAAS_MCP_ENABLED=true \
  -e KAAS_MCP_TOKEN=your-secret-token \
  kaas

MCP endpoint: http://<host>:8080/mcp
Authorization: Bearer your-secret-token

Full Environment Variable Reference

Env Var	Overrides	Default
LLM_API_KEY	[llm] api_key	(required)
LLM_BASE_URL	[llm] base_url	https://api.openai.com/v1
LLM_MODEL	[llm] model	gpt-4o-mini
LLM_SUMMARIZE_MODEL	[llm] summarize_model	same as LLM_MODEL
KAAS_MCP_ENABLED	[ai.mcp] enabled	false
KAAS_MCP_TOKEN	[ai.mcp] token	(empty = no auth)
KAAS_WEB_DIR	[server] web_dir	/app/web/dist

---

Option B: CLI Install

1. Install the Binary

curl -fsSL https://raw.githubusercontent.com/bybit-exchange/kaas/main/install.sh | sh

Supported platforms: Linux/macOS, amd64/arm64.

The script installs the kaas binary to ~/.local/bin/kaas and data to ~/.local/share/kaas.

2. Set Environment Variables

export LLM_API_KEY="sk-xxx"                       # Required — your API key
export LLM_BASE_URL="https://api.openai.com/v1"   # Optional — defaults to OpenAI
export LLM_MODEL="gpt-4o-mini"                    # Optional — defaults to gpt-4o-mini

Add these to your shell profile (~/.bashrc, ~/.zshrc) to persist across sessions.

3. Start the Service

kaas serve

The server starts at http://localhost:8080 by default.

Uninstall

rm -rf ~/.local/share/kaas ~/.local/bin/kaas

---

Option C: Agent-First (No Docker)

If you already work inside a coding agent (Claude Code, Codex, openclaw, etc.), you can skip Docker entirely. Copy the following prompt and paste it into your agent:

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.

The agent will:

1. Install kb-ai — tries uv tool install, then pipx, then pip:

   uv tool install "git+https://github.com/bybit-exchange/kaas.git#subdirectory=py"

2. Ask for LLM credentials — you provide your API key (and optionally base URL / model).
3. Ask which sources to distill — current directory, other paths, URLs, or pasted text.
4. Run kb-ai distill — compiles your content into a .kaas/ wiki.
5. Wire up MCP — so future agent sessions can query the wiki:

   claude mcp add kaas -- env KAAS_KB_DIR=$(pwd)/.kaas LLM_API_KEY=$LLM_API_KEY kb-ai mcp

After setup, start a new agent session and ask questions about your content — answers come from the compiled wiki via the ask tool.

---

Verify Installation

Regardless of which path you chose (Docker or CLI), verify that KaaS is running:

Web UI

Open your browser:

http://localhost:8080

You should see the KaaS dashboard.

Health Check

curl http://localhost:8080/healthz

A healthy instance returns HTTP 200.

---

Next Steps

• Configuration — customize LLM providers, MCP settings, and storage options
• Your First Knowledge Base — submit content and build a structured wiki