ktx/docs-site/content/docs/getting-started/quickstart.mdx

---
title: Quickstart
description: Set up KTX and build your first context in under 10 minutes.
---

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.

If you are a coding assistant trying to decide which KTX docs page to read, start with the [Agent Quickstart](/docs/ai-resources/agent-quickstart). This page is the human setup walkthrough.

## Workflow summary

Use this sequence when you are setting up KTX in an analytics project:

1. `npm install -g @kaelio/ktx` — install the published KTX CLI from npm.
2. `ktx setup` — create or resume a KTX project.

The setup wizard is stateful. If it exits before completion, rerun `ktx setup` in the same project directory to resume from the first incomplete step.

## Install and run setup

Install the published [`@kaelio/ktx`](https://www.npmjs.com/package/@kaelio/ktx) CLI:

```bash
npm install -g @kaelio/ktx
```

Then run the setup wizard:

```bash
ktx setup
```

The local checkout flow is only for contributors working on KTX itself. See [Contributing](/docs/community/contributing) for that setup.

The wizard walks through six steps. You can go back at any point, and if you exit early, rerunning `ktx setup` 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:

```
◆  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:

```
◆  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.

```
◆  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 managed Python runtime. No API key is needed. KTX can install and start the runtime during setup; to prepare it ahead of time, run:

```bash
ktx dev runtime install --feature local-embeddings --yes
ktx dev runtime start --feature local-embeddings
```

## 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:

```
◆  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:

```
◇  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.

```
◆  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:

```
◆  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.

```
◆  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 wiki pages.

For a small database (under 50 tables), this takes a few minutes. Larger warehouses can take longer. You can press <kbd>d</kbd> 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 --project-dir /home/user/analytics
Status: ktx status --project-dir /home/user/analytics
```

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:

```
◆  How should agents use this KTX project?
│  ○ CLI tools and skills
```

Then select which agents to install for:

```
◆  Which agent targets should KTX install?
│  ◻ Claude Code
│  ◻ Codex
│  ◻ Cursor
│  ◻ OpenCode
│  ◻ Custom agent (.agents)
```

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

**Custom agent** uses the universal `.agents` target for agents that can read project-local skills.

## Generated files

KTX writes project state as plain files so agents can inspect and edit changes in git.

| Path | Created by | Purpose |
|------|------------|---------|
| `ktx.yaml` | `ktx setup` | Main project configuration: connections, LLM settings, embeddings, and context sources |
| `.ktx/secrets/*` | `ktx setup` when file-backed secrets are selected | Local secret files referenced from `ktx.yaml`; do not commit these |
| `semantic-layer/<connection-id>/*.yaml` | context build, ingestion, or direct file edits | Semantic source definitions agents use for SQL generation |
| `wiki/global/*.md` | ingestion, memory capture, `ktx wiki write --scope global`, or direct file edits | Shared business context and metric definitions |
| `wiki/user/<user-id>/*.md` | memory capture, `ktx wiki write --scope user`, or direct file edits | User-scoped notes for one agent/user context |
| `.claude/skills/ktx/SKILL.md`, `.agents/skills/ktx/SKILL.md` | CLI-mode agent integration setup | Agent instructions for calling public `ktx` commands |

## Verify it worked

Check your project status:

```bash
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)
```

## Common errors

| Error or symptom | Likely cause | Recovery |
|------------------|--------------|----------|
| `ktx: command not found` | The KTX package is not installed globally, or the shell cannot find the global binary | Run `npm install -g @kaelio/ktx` and open a new shell |
| LLM health check fails | Missing, invalid, or unauthorized Anthropic API key | Export `ANTHROPIC_API_KEY` or rerun `ktx setup` and choose the file-backed secret option |
| OpenAI embedding check fails | `OPENAI_API_KEY` is missing when OpenAI embeddings are selected | Export `OPENAI_API_KEY`, or rerun setup and choose local sentence-transformers embeddings |
| Local embeddings hang or fail | The managed Python runtime cannot start or the local model runtime is unavailable | Install `uv`, run `ktx dev runtime status`, then run `ktx dev runtime install --feature local-embeddings --yes` and rerun setup |
| Database connection test fails | Credentials, network access, warehouse, database, or schema value is wrong | Test the same URL with the database's native client, then rerun `ktx setup` and reconfigure the connection |
| `KTX context built: no` in `ktx status` | Setup saved configuration but did not build context | Run `ktx setup` and choose to build context now |
| Agent integration is incomplete | Setup skipped the agents step or the target was not installed | Run `ktx setup --agents --target codex --project` using the target you need |

## Next steps

- **Build more context** — learn about [scanning](/docs/guides/building-context), relationship detection, and ingestion workflows in the Building Context guide.
- **Refine your semantic layer** — the [Writing Context](/docs/guides/writing-context) guide covers source YAML, measures, joins, and wiki pages.
- **Understand the architecture** — read [The Context Layer](/docs/concepts/the-context-layer) to learn why a context layer is more than a semantic layer.
- **Connect more agents** — see the [Agent Clients](/docs/integrations/agent-clients) integration page for per-tool setup details.