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 connect to. 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 builds fast
schema context:

```
Testing postgres-warehouse
  Connection test passed
  Driver: PostgreSQL - Tables: 42

Building schema context for postgres-warehouse
  Running fast database ingest

Schema context complete for postgres-warehouse
  Changes: 42 new tables

Database ready
  postgres-warehouse - PostgreSQL - schema context complete
```

For PostgreSQL, Snowflake, and BigQuery, the wizard can enable query-history
ingest when the warehouse history feature is available. Query history is stored
under `connections.<id>.context.queryHistory` in `ktx.yaml`.

## 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 builds agent-ready context. It uses the database context
depth saved by setup and ingests metadata from any configured context sources.

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

Fast database context builds deterministic schema grounding. Deep database
context also generates AI descriptions, embeddings, and relationship evidence
when those capabilities are configured.

For a small database (under 50 tables), this can take a few minutes. Larger
warehouses can take longer. Context builds run in the foreground; press
<kbd>Ctrl+C</kbd> to stop the current run and rerun `ktx setup` or `ktx ingest`
when you are ready to try again.

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

```
KTX context is ready for agents.

Databases:
  postgres-warehouse: deep context 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, or direct file edits | Shared business context and metric definitions |
| `wiki/user/<user-id>/*.md` | memory capture 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)
Databases 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` using the target you need |

## Next steps

- **Build more context** — learn about [database ingest](/docs/guides/building-context), relationship detection, and source 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.