Skip to content

Quick start

This guide takes you from a running KDBL Context Lake (K-Lake) deployment to your first grounded, verifiable answer — indexing a source, extracting its content, searching it, and opening the original file behind any result to confirm it.

It assumes your administrator has deployed K-Lake and given you two things: the URL of your K-Lake instance (for example https://kdbl.example.com) and a personal access token (PAT). If you are the administrator and still need to deploy, install it on your cluster with the production deployment guide, or stand up an evaluation stack on a single VM in one command (see the proof of concept); the rest of this guide picks up once K-Lake is running.

Administrators: once the cluster is up, create a customer's tenant + first admin user + PAT in one step with kdbl-control onboard <slug> --name "<Display Name>" (cluster-admin token; see CLI reference → onboard). Hand the printed PAT to the user — that's the token this guide expects below.

You will use one or more of three interchangeable interfaces — the web console, the kdbl-control CLI, and the REST API. They act on the same data, so pick whichever suits you. Every action is scoped to your tenant and audited.

1. Sign in

Open your K-Lake URL in a browser. Sign in with your PAT (paste it into Personal Access Token and click Sign in with PAT) or, if your tenant uses single sign-on, type your tenant's name under Tenant slug and click Sign in with SSO. You land on Overview, which shows queue health and a per-source summary. Every page is in the sidebar on the left; see Finding your way around.

Tip: press ⌘K (Mac) or Ctrl+K anywhere in the console to open the command palette, then type where you want to go, an action such as add source, or words from a document. See Keyboard shortcuts and the command palette.

To use the CLI or API, set these once in your shell:

export KDBL_URL=https://kdbl.example.com
export KDBL_TOKEN=kdblpat_<your-token>

Need a fresh token? An administrator can mint one in the console under AI access (MCP) › Tokens (or press ⌘K / Ctrl+K and pick Mint an MCP access token): name it and click Mint token. The value is shown once — copy it immediately.

2. Add a source

A source is one location K-Lake tracks — an S3 bucket, an Azure Blob container, an SMB/CIFS share, an NFS export, or a SharePoint / OneDrive drive. The quickest start is a small S3 bucket or Azure Blob container.

Guided (CLI): kdbl-control --api-url "$KDBL_URL" --api-token "$KDBL_TOKEN" init walks you through this whole section — connect a source, enable extraction, and start the first crawl — in one interactive flow. The manual steps below are the same thing, broken out.

Console: Sources › New source (or press ⌘K / Ctrl+K and pick Add a source). Choose S3 under Protocol, enter the bucket, region and credentials, and check the Source ID that is filled in for you (e.g. s3://docs-bucket; edit it if you want a different stable ID). Test connection checks the details; Create source saves it.

CLI — S3:

printf '%s' "$AWS_SECRET_ACCESS_KEY" | kdbl-control \
  --api-url "$KDBL_URL" --api-token "$KDBL_TOKEN" \
  source add-s3 \
  --source-id 's3://docs-bucket' \
  --bucket docs-bucket --region us-east-1 \
  --access-key-id AKIA... --secret-access-key-stdin

CLI — SMB/CIFS: two backends — smb (userspace, no special privileges) and smbfs (kernel CIFS mount; adds NTFS ACLs, SMB3 multichannel, and backup-operator intent). The password is read from stdin, like the S3 secret.

# userspace backend
printf '%s' "$SMB_PASSWORD" | kdbl-control \
  --api-url "$KDBL_URL" --api-token "$KDBL_TOKEN" \
  source add-smb \
  --source-id 'smb://fileserver/share' \
  --server fileserver --share share --username svc-kdbl

# kernel-mount backend (NTFS ACLs etc.)
printf '%s' "$SMB_PASSWORD" | kdbl-control \
  --api-url "$KDBL_URL" --api-token "$KDBL_TOKEN" \
  source add-smbfs \
  --source-id 'smbfs://fileserver/share' \
  --server fileserver --share share --username svc-kdbl --backup-intent

The secret (S3) or password (SMB) is read from stdin so it never lands in your shell history. Credentials are encrypted at rest. See Sources for NFS, and for narrowing a source to a subtree.

The web console's New source form and the source add-* CLI commands turn content extraction on by default (any file type), so the source you just added is already set to become searchable after its first crawl. Pass --no-extract (CLI) or untick Enable content extraction (console) to opt out. The raw REST POST /sources does not auto-enable — use step 3 for that.

3. Tune extraction (optional)

Extraction reads each file's content so it becomes searchable. It's on by default from step 2, so you can skip straight to the crawl — use this step only to restrict by file type, or to enable extraction if you added the source with --no-extract or via the raw API.

Console: open the source, then its Configure tab. Under Smart Actions, the Content extraction step has Enable / Disable; click its Configure to set an Extension allowlist such as pdf, docx. See Smart Actions.

CLI:

kdbl-control --api-url "$KDBL_URL" --api-token "$KDBL_TOKEN" \
  source extract enable --source-id 's3://docs-bucket' --extensions pdf,docx

An extraction config change (whether from add-* or this command) takes effect within ~30 s. If you crawl within that window the files are listed but not yet queued for extraction — just recrawl with --force-reextract (see the next step) and they'll be picked up.

4. Crawl the source

A crawl walks the source, records every file it finds, and — with extraction enabled above — queues each eligible file for content extraction.

Console: open the source and click Run crawl (in the command palette, #docs-bucket jumps straight to the source).

CLI / API:

kdbl-control --api-url "$KDBL_URL" --api-token "$KDBL_TOKEN" crawl --source-id 's3://docs-bucket'

curl -X POST -H "Authorization: Bearer $KDBL_TOKEN" \
  "$KDBL_URL/api/sources/s3%3A%2F%2Fdocs-bucket/crawl"

The source page shows live file and byte counts as the crawl runs, and extracted content becomes searchable as soon as each file finishes. (Source IDs are URL-encoded in API paths: s3://docs-bucket → s3%3A%2F%2Fdocs-bucket.)

Enabled extraction on an already-crawled source? A normal recrawl skips unchanged files, so it won't pick them up for extraction. Force a one-time full re-extraction: 

kdbl-control --api-url "$KDBL_URL" --api-token "$KDBL_TOKEN" \
  crawl --source-id 's3://docs-bucket' --force-reextract

5. Search your content

Console: open Search in the sidebar, enter a query and press Search. It searches every source you can see; to narrow it to one, pick it under Search in. Each result shows the file, an in-document locator (page / timestamp), and a highlighted snippet. For a quick look without leaving the page you are on, type the words into the command palette (⌘K / Ctrl+K): it lists the top five documents, and More results opens the full Search page.

API:

curl -H "Authorization: Bearer $KDBL_TOKEN" \
  "$KDBL_URL/api/sources/s3%3A%2F%2Fdocs-bucket/content/search?q=invoice"

Search is relevance-ranked: every bare word you type contributes to the score and results come back best-first, with a rare term (a contract reference, an incident ID, a proper noun) outranking a common one. A result that contains your words as an exact phrase, in order, is ranked above everything else and badged exact phrase in the console (match_tier: "phrase" on the API; all = every term present but scattered, partial = some terms).

Four operators narrow the match set:

Operator Meaning
"quoted phrase" The result must contain those words together, in order.
-word, -"quoted phrase" Exclude. A query needs at least one positive term.
A OR B At least one of the two. Groups quoted phrases or single words.
INC-2026-0714 A reference-like token (hyphens, slashes or dots with a digit, or three or more parts) is matched as a whole, so a ticket or contract number returns only the files that carry it.

File names count. A document whose path or original file name matches is found even when its text does not repeat the words — a title, a contract reference in a filename or a folder name are all searchable as-is. Those hits are badged filename (name_match: true).

One row per document. The console's Group by document toggle (on by default; ?group=file on the API) folds a document's matching passages under its best one, with the count and up to three of the others, so one long document does not fill the page.

If a query still misses, rephrase it in the wording the document itself would use — a section title, the printed line item, the formal name — and quote the part you are sure of.

6. Open the original to verify

Every result is traceable to its source. In the console, each search hit and the file-detail page carry an Open original link (and Download); the API returns the same as a signed url on each hit. Clicking it re-fetches the original file on demand so you can confirm exactly where an answer came from.

Access is always enforced: the link is short-lived, re-checks your permissions at open time, and is audited — you only ever see files you're authorized to see.

7. (Optional) Connect an AI assistant

K-Lake can serve your content to an AI assistant over the Model Context Protocol (MCP), so the assistant answers only from your knowledge base and cites a source for every fact — with the same per-user security and auditing.

Ask your administrator to enable MCP on your instance, then point your client at it. See Connecting MCP clients for Claude Desktop and other clients, and the MCP skills reference for the available tools.

Next steps