Configuration

KaaS uses a single TOML file for configuration. This tutorial walks you through the most important settings and how to customize them for your environment.

Configuration File

KaaS reads its configuration from etc/kaas.toml relative to the working directory. When you installed via the CLI installer, a default config was placed at ~/.local/share/kaas/etc/kaas.toml.

To start the server with a specific config file:

kaas serve -f /path/to/kaas.toml

The file is organized into sections: [llm], [server], [storage], [worker], [ai], [ai.mcp], and others. Let's walk through them in order of importance.

LLM Settings

This is the most critical section — it tells KaaS which LLM to use for the knowledge compilation pipeline and chat.

[llm]
api_key = "sk-..."
base_url = "https://api.openai.com/v1"
model = "gpt-4o-mini"

KaaS works with any OpenAI-compatible API. Here are examples for common providers:

OpenAI

[llm]
api_key = "sk-proj-xxxxx"
base_url = "https://api.openai.com/v1"
model = "gpt-4o-mini"

DeepSeek

[llm]
api_key = "sk-xxxxx"
base_url = "https://api.deepseek.com"
model = "deepseek-chat"

Ollama (local)

[llm]
api_key = "ollama"          # Ollama ignores this, but the field is required
base_url = "http://localhost:11434/v1"
model = "llama3.1"

Summarize Model

By default, the summarization step uses the same model. If you want a cheaper/faster model for summaries, set summarize_model explicitly:

[llm]
model = "gpt-4o"
summarize_model = "gpt-4o-mini"

Server Settings

Controls the HTTP server's listening address:

[server]
host = "0.0.0.0"
port = 8080

For most deployments, the defaults work fine. Change host to 127.0.0.1 if you only want local access without a reverse proxy.

Storage

KaaS stores job state in a database and outputs the compiled wiki as Markdown files:

[storage]
driver = "sqlite"
sqlite_path = "./data/kaas.db"
kb_dir = "./data"

Field	Purpose
driver	"sqlite" (default) or "mysql"
sqlite_path	Path to the SQLite database file
kb_dir	Directory where compiled wiki Markdown is written

The kb_dir is where your knowledge base lives — this is the folder you'd point an MCP client at, or commit to git for version control.

MySQL

For production with multiple replicas, switch to MySQL:

[storage]
driver = "mysql"
mysql_dsn = "user:pass@tcp(127.0.0.1:3306)/kaas"
kb_dir = "./data"

Worker Tuning

The worker section controls the compilation pipeline's concurrency:

[worker]
extract_workers = 4
pipeline_concurrency = 2
poll_interval_ms = 1000
lease_timeout_sec = 300
cb_failure_threshold = 5
cb_cooldown_sec = 30

Key settings to adjust:

Field	Default	When to change
extract_workers	4	Increase if your LLM provider allows higher concurrency
pipeline_concurrency	2	Increase to process more documents simultaneously
cb_failure_threshold	5	Circuit breaker — trips after N consecutive LLM failures
cb_cooldown_sec	30	How long to wait before retrying after circuit breaker trips

WARNING

Setting extract_workers too high may trigger rate limits on your LLM provider. Start with the defaults and increase gradually.

MCP Settings

KaaS can expose an MCP (Model Context Protocol) endpoint so remote AI agents can query your knowledge base:

[ai.mcp]
enabled = false
token = ""
timeout_sec = 120

To enable it:

[ai.mcp]
enabled = true
token = "your-secret-token"    # Leave empty for intranet-only deployments
timeout_sec = 120

Once enabled, agents connect at http://<host>:8080/mcp with Authorization: Bearer your-secret-token.

# Example: connect Claude Code to a remote KaaS instance
claude mcp add --transport http kaas http://your-server:8080/mcp

Environment Variables

Every TOML setting can be overridden with environment variables. This is the recommended approach for Docker deployments and CI/CD pipelines — keep secrets out of config files.

Env Var	Overrides	Default
LLM_API_KEY	[llm] api_key	(empty)
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 model
KAAS_MCP_ENABLED	[ai.mcp] enabled	false
KAAS_MCP_TOKEN	[ai.mcp] token	(empty)
KAAS_AI_MCP_URL	[ai] mcp_url	(empty)

Environment variables always take precedence over the TOML file.

Docker vs CLI

How you configure KaaS depends on your deployment method:

Docker: use environment variables

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=my-secret \
  kaas

This keeps secrets out of image layers and makes configuration changes simple (just restart the container with new env vars).

CLI: edit the TOML file

# Edit the config
vim etc/kaas.toml

# Start with your config
kaas serve -f etc/kaas.toml

Or combine both — use the TOML file for non-sensitive defaults and env vars for secrets:

export LLM_API_KEY="sk-xxx"
kaas serve -f etc/kaas.toml

Next Steps

• For a complete field-by-field reference, see Configuration Reference
• For the full list of environment variables, see Environment Variables
• Ready to process your first documents? Continue to Your First Knowledge Base