Documentation
Home GitHub

Configuration

Configure KuraDB credentials, local state, HTTP binding, and compile-time service behavior.

Credential

KuraDB requires one external credential:

Name Required Consumer Purpose
OPENAI_API_KEY Yes internal/openai.New Authorizes text-embedding-3-small requests

The daemon initializes the KuraDB keychain context and retrieves OPENAI_API_KEY through go-pkg/filesystem/keychain. KuraDB does not define additional runtime environment variables in its application source.

Do not write the credential into config.json, command arguments, logs, or documentation. Make it available through the keychain integration before starting the daemon; startup exits if the value is unavailable.

Configuration directory

All runtime state is rooted at ~/.config/kuradb/.

Path Kind Purpose
config.json Durable JSON Optional pinned HTTP port
db.json Durable JSON Registered database names and creation timestamps
global.db Durable SQLite Persisted query embedding cache
{name}/data.db Durable SQLite Authoritative chunks, dismissal state, and embeddings
{name}/inbox/ Watched directory Files accepted by the ingestion pipeline
{name}/record.json Durable JSON Watcher snapshot of file metadata
runtime.uid Ephemeral JSON Daemon UID, PID, and start time
endpoint Ephemeral text Current local HTTP base URL
daemon.log Log Detached daemon stdout and stderr

Each database also has a convenience symlink at ~/Kura_{name} pointing to its inbox.

HTTP port

config.json currently has one supported property:

{
  "port": 8080
}
Property Type Default Rules
port integer 0 / omitted Must be in the range 1–65535 when set through the CLI

Manage the value through KuraDB rather than editing JSON manually:

kura port set 8080
kura port clear

port set persists the value and restarts the daemon. port clear writes an unpinned configuration, which takes effect after the next manual start.

When no port is pinned, KuraDB tries up to 10 random ports from 10000 through 65535. Both fixed and random listeners bind only to 127.0.0.1; the published URL uses localhost.

Fixed service constants

The following behavior is compiled into the current binary rather than exposed as configuration:

Setting Value Source
File polling interval 10 seconds cmd/app/main.go
Embedding polling interval 5 seconds cmd/app/main.go
Embedding batch size 64 chunks cmd/app/main.go
OpenAI model text-embedding-3-small internal/openai/openai.go
Embedding dimensions 512 internal/openai/openai.go
OpenAI request timeout 1 minute internal/openai/openai.go
HTTP read-header timeout 5 seconds cmd/app/http.go
HTTP shutdown timeout 5 seconds cmd/app/http.go
Default search limit 10 internal/api/handler/keyword.go
Maximum search limit 100 internal/api/handler/keyword.go
Semantic score cutoff 0.3 internal/api/handler/semantic.go

Endpoint discovery

After the listener is ready, KuraDB writes a URL to ~/.config/kuradb/endpoint:

BASE="$(cat ~/.config/kuradb/endpoint)"
curl "$BASE/api/health"

The launcher waits up to 10 seconds for this file. Graceful shutdown removes it, so consumers should read it again after every restart.

Database availability

Registry changes are durable immediately, but the daemon constructs its loaded database map only during startup. After kura add, restart KuraDB before sending searches to the new name. /api/list exposes registered and loaded separately so clients can detect this state.

Platform constraints

Use a local APFS/HFS+ filesystem on macOS or ext4/xfs on Linux. The watcher depends on reliable POSIX directory mtime semantics and does not support Windows, SMB, NFS, or FUSE mounts.

中文