Quickstart

This guide walks you through ktx setup — an interactive wizard that configures your LLM provider, connects your database, optionally ingests from your existing tools, builds context, and installs agent integration.

Prerequisites

Node.js 22+ and pnpm
An Anthropic API key for LLM-powered enrichment and ingestion
A database connection — PostgreSQL, Snowflake, BigQuery, ClickHouse, MySQL, SQL Server, or SQLite
Optionally, a dbt project, LookML repo, Metabase instance, or other context source

Install and run setup

KTX is currently used from a local checkout or linked workspace CLI. Build and link the CLI first:

git clone https://github.com/kaelio/ktx.git
cd ktx
pnpm install
pnpm run setup:dev
pnpm run link:dev

Then run the setup wizard in the directory where you want your KTX project:

ktx setup

The wizard walks through six steps. You can go back at any point, and if you exit early, running ktx setup again resumes where you left off.

Step 1: Configure LLM

KTX uses an Anthropic model to enrich schema descriptions, generate semantic sources during ingestion, and reconcile metadata from your tools.

The wizard asks how to find your API key:

zsh

◆  How should KTX find your Anthropic API key?
│  ○ Use ANTHROPIC_API_KEY from the environment
│  ○ Paste a key and save it as a local secret file

If you choose to paste a key, KTX saves it in .ktx/secrets/anthropic-api-key with local file permissions. Your ktx.yaml stores a file: reference, never the raw key.

Next, choose a model:

zsh

◆  Which Anthropic model should KTX use?
│  ○ Claude Sonnet 4.6 (recommended)
│  ○ Claude Opus 4.6
│  ○ Claude Haiku 4.5
│  ○ Enter a model ID manually

KTX runs a health check to verify your key and model work before saving.

Step 2: Configure embeddings

KTX uses embeddings for semantic search over sources, wiki content, schema metadata, and relationship evidence.

zsh

◆  Which embedding option should KTX use?
│  ○ Local sentence-transformers embeddings
│  ○ OpenAI embeddings (recommended)

OpenAI embeddings use text-embedding-3-small (1536 dimensions) and require an OPENAI_API_KEY.

Local embeddings use all-MiniLM-L6-v2 (384 dimensions) via the KTX Python daemon. No API key is needed. If you run the daemon as a long-lived HTTP service, start it with:

ktx-daemon serve-http --host 127.0.0.1 --port 8765

Step 3: Connect a database

Select one or more databases for KTX to scan. The wizard supports SQLite, PostgreSQL, MySQL, ClickHouse, SQL Server, BigQuery, and Snowflake.

For PostgreSQL, you can enter connection details field by field or paste a connection URL:

zsh

◆  How do you want to connect to PostgreSQL?
│  ○ Enter connection details (host, port, database, user)
│  ○ Paste a connection URL

If your URL contains credentials, KTX saves it to .ktx/secrets/ and writes a file: reference in ktx.yaml. You can also use env:DATABASE_URL to reference an environment variable.

After connecting, KTX automatically runs a connection test and a structural scan:

zsh

◇  Testing postgres-warehouse
│  ✓ Connection test passed
│  Driver: PostgreSQL · Tables: 42
│
◇  Scanning postgres-warehouse
│  ✓ Structural scan completed
│  Changes: 42 new tables
│
◇  Primary source ready
│  postgres-warehouse · PostgreSQL · structural scan complete

For Snowflake and BigQuery, the wizard offers Historic SQL configuration for query history views. For PostgreSQL, enable Historic SQL with --enable-historic-sql when pg_stat_statements is configured.

Step 4: Add context sources

Context sources let KTX ingest metadata from your existing analytics tools. This step is optional — you can skip it and add sources later.

zsh

◆  Which context sources should KTX ingest?
│  ◻ dbt
│  ◻ MetricFlow
│  ◻ Metabase
│  ◻ Looker
│  ◻ LookML
│  ◻ Notion

For dbt, point KTX at a local path or git URL. KTX reads your dbt_project.yml and schema files to extract model metadata:

zsh

◆  dbt source location
│  ○ Local path
│  ○ Git URL

For Metabase and Looker, you provide an API URL and credentials. KTX maps BI databases to your KTX primary source connections so it knows which warehouse tables the BI metadata refers to.

Context sources are saved to ktx.yaml and built during the next step.

Step 5: Build context

This is where KTX does the heavy lifting. It runs an enriched scan of your database (generating AI-powered column and table descriptions) and ingests metadata from any configured context sources.

zsh

◆  Build KTX context for agents?
│  ○ Build context now (recommended)
│  ○ Leave context unbuilt and exit setup

The build scans each primary source with LLM enrichment, detects table relationships, and runs ingestion agents that reconcile metadata from your context sources into semantic-layer YAML files and knowledge pages.

For a small database (under 50 tables), this takes a few minutes. Larger warehouses can take longer. You can press d to detach and let it run in the background:

KTX context build
Run: setup-context-local-abc123
Project: /home/user/analytics

Detach: press d to leave this running.
Resume: ktx setup context watch setup-context-local-abc123
Status: ktx setup context status setup-context-local-abc123

When the build completes, KTX verifies that agent-ready context was produced:

KTX context is ready for agents.

Primary sources:
  postgres-warehouse: enriched scan complete

Context sources:
  dbt-main: memory update complete

Verification:
  Agent context: ready
  Semantic search: ready

Step 6: Install agent integration

The final step connects KTX to your coding agent. Choose how agents should access the project:

zsh

◆  How should agents use this KTX project?
│  ○ CLI tools and skills
│  ○ MCP server config
│  ○ Both

Then select which agents to install for:

zsh

◆  Which agent targets should KTX install?
│  ◻ Claude Code
│  ◻ Codex
│  ◻ Cursor
│  ◻ OpenCode

CLI mode writes a skill file (e.g., .claude/skills/ktx/SKILL.md) that teaches the agent to call KTX commands directly.

MCP mode writes an MCP server configuration (e.g., .mcp.json) that lets the agent call KTX tools like sl_query, knowledge_search, and sl_write_source over the Model Context Protocol.

Verify it worked

Check your project status:

ktx status

KTX project: /home/user/analytics
Project ready: yes
LLM ready: yes (claude-sonnet-4-6)
Embeddings ready: yes (text-embedding-3-small)
Primary sources configured: yes (postgres-warehouse)
Context sources configured: yes (dbt-main)
KTX context built: yes
Agent integration ready: yes (claude-code:project)

List your semantic sources:

ktx sl list

Query through the semantic layer:

ktx sl query \
  --connection-id postgres-warehouse \
  --measure orders.total_revenue \
  --dimension orders.status \
  --order-by orders.total_revenue:desc \
  --limit 5 \
  --format sql

This outputs the generated SQL. Add --execute to run it against your warehouse:

ktx sl query \
  --connection-id postgres-warehouse \
  --measure orders.total_revenue \
  --dimension orders.status \
  --order-by orders.total_revenue:desc \
  --limit 5 \
  --execute --max-rows 10

Next steps

Build more context — learn about scanning, relationship detection, and ingestion workflows in the Building Context guide.
Refine your semantic layer — the Writing Context guide covers source YAML, measures, joins, and knowledge pages.
Understand the architecture — read The Context Layer to learn why a context layer is more than a semantic layer.
Connect more agents — see the Agent Clients integration page for per-tool setup details.

On this page