Documentation
Home GitHub

Getting Started

Install KuraDB, register a database, index files, and run your first read-only search.

Prerequisites

Requirement Details
Go Go 1.25.1 or newer
Platform macOS on APFS/HFS+ or Linux on ext4/xfs
Credential OPENAI_API_KEY available through the KuraDB keychain integration
Network Access to https://api.openai.com/v1/embeddings

KuraDB relies on POSIX directory modification-time behavior. Windows and unreliable SMB, NFS, or FUSE mounts are outside the supported platform contract.

Install

With go install

go install github.com/agenvoy/kuradb/cmd/app@latest

The installed command is expected to be named kura.

From source

git clone https://github.com/pardnchiu/KuraDB.git
cd KuraDB
make build

The Makefile writes the binary to bin/kura. make app stops a prior process, builds the binary, installs it at /usr/local/bin/kura, and starts it.

Register a database

kura add my_docs

This command:

  1. Sanitizes whitespace in the name to underscores.
  2. Registers my_docs in ~/.config/kuradb/db.json.
  3. Creates ~/.config/kuradb/my_docs/inbox/.
  4. Creates ~/Kura_my_docs as a symlink to the inbox.

A database added while the daemon is running is not hot-loaded. Restart KuraDB before querying the new database.

Start the daemon

kura

The foreground launcher starts a detached --daemon process and waits up to 10 seconds for the endpoint file. When ready, it prints a URL such as:

http://localhost:43127

The daemon loads registered databases, restores caches from SQLite, starts watcher and embedding loops for each loaded database, and binds the read-only HTTP API to 127.0.0.1.

Index a file

cp document.md ~/Kura_my_docs/

The watcher polls every 10 seconds. Changed files are parsed and written to SQLite; the embedding scheduler polls every 5 seconds and processes at most 64 pending chunks per batch.

Read the selected endpoint and query both strategies:

BASE="$(cat ~/.config/kuradb/endpoint)"
curl "$BASE/api/search?db=my_docs&q=what+is+RAG&limit=5"

Use target=keyword or target=semantic to run only one strategy:

curl "$BASE/api/search?db=my_docs&q=vector+cache&target=semantic"

Verify service state

curl "$BASE/api/health"
curl "$BASE/api/list"

/api/health returns plain text OK. /api/list returns both the currently loaded database names and registry entries; the two can differ until the daemon is restarted.

Stop or reconfigure

kura port set 8080
kura port clear
kura stop

port set saves the port and restarts the daemon. port clear removes the pin but requires the next manual restart to take effect.

Next steps

中文