Documentation v0.6.0
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 and kura mcp initialize the KuraDB keychain context (service kuradb) and resolve OPENAI_API_KEY through go-pkg/filesystem/keychain. The system keychain is checked first; the environment variable is read only when the keychain has no value:

Platform Lookup order
macOS security find-generic-password -s kuradb -a OPENAI_API_KEY → environment variable
Linux secret-tool lookup service kuradb account OPENAI_API_KEY → ~/.config/kuradb/.secrets (OPENAI_API_KEY=...) → environment variable

A value stored in the keychain takes precedence, so exporting a different OPENAI_API_KEY has no effect while a keychain entry exists. 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 or the environment before starting the daemon; startup exits if neither provides a value.

Configuration directory

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

Path Kind Purpose
config.json Durable JSON Optional pinned HTTP port and remote MCP flag
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 two supported properties:

{
  "port": 8080,
  "remote": false
}
Property Type Default Rules
port integer 0 / omitted Must be in the range 1–65535 when set through the CLI
remote boolean false / omitted Mounts the MCP endpoint at /mcp when true

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.

Remote MCP endpoint

The MCP endpoint on the HTTP listener is opt-in:

kura remote enable
kura remote disable

Both commands persist the remote flag and restart a running daemon, because routes are mounted during startup. While the flag is false the daemon serves /api/* normally and answers 404 at /mcp. The stdio transport, kura mcp, ignores this setting entirely.

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/search/group.go
Maximum search limit 100 internal/search/group.go
Semantic score cutoff 0.3 internal/search/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.

中文