spelunk config reference

spelunk reads configuration from two TOML files, layered with environment variable overrides.

Config files

Load order (later overrides earlier):

1. Defaults
2. ~/.config/spelunk/config.toml (global personal)
3. .spelunk/config.toml, discovered by walking up from the current directory (project-level, team-wide) — only server_url / server_key / project_id (and their deprecated aliases) are read from this file
4. Environment variables: SPELUNK_SERVER_URL, SPELUNK_SERVER_KEY, SPELUNK_PROJECT_ID

Override the global config file path with -c, --config <path> on any command.

Fields

db_path

• Type: path
• Default: ~/.config/spelunk/index.db

Path to the SQLite database file.

models_dir

• Type: path
• Default: ~/.config/spelunk/models

Directory where embedding model weights are cached (used by the native fastembed-rs backend).

embedding_model

• Type: string
• Default: text-embedding-embeddinggemma-300m-qat

Model ID for embeddings.

• LM Studio: the model's API key shown in the LM Studio UI (e.g. text-embedding-embeddinggemma-300m-qat).
• Native (Metal/fastembed): a HuggingFace repo ID (e.g. google/embeddinggemma-300m).

llm_model

• Type: string, optional
• Default: unset

Model ID for the LLM used by spelunk explore, spelunk memory harvest, and spelunk plan create. When unset, commands that require a chat model are unavailable. For LM Studio, this is the model's API key (e.g. google/gemma-3n-e4b).

batch_size

• Type: integer
• Default: 32

Default embedding batch size — lower if you run out of memory. Can be overridden per-run with spelunk index --batch-size <n>.

api_base_url

• Type: string
• Default: http://127.0.0.1:1234
• Alias: lmstudio_base_url (accepted, deprecated)

Base URL for an OpenAI-compatible inference API (e.g. LM Studio, Ollama, vLLM), used when you point spelunk at your own embedding/LLM endpoint instead of the bundled native embedder.

server_url

• Type: string, optional
• Default: unset
• Alias: memory_server_url (accepted, deprecated)
• Env override: SPELUNK_SERVER_URL (also accepts the deprecated SPELUNK_MEMORY_SERVER_URL)

URL of a spelunk-server instance, e.g. http://spelunk.internal:7777. When set, the CLI operates in Tier 1 (server-connected) mode, enabling semantic search, embedding, explore, and memory-sync features. Set this in .spelunk/config.toml (project-level) or via SPELUNK_SERVER_URL.

server_key

• Type: string, optional
• Default: unset
• Alias: memory_server_key (accepted, deprecated)
• Env override: SPELUNK_SERVER_KEY

Bearer token for spelunk-server auth. Set this in ~/.config/spelunk/config.toml (personal) or via SPELUNK_SERVER_KEY — do not commit it to .spelunk/config.toml.

project_id

• Type: string, optional
• Default: unset (derived at runtime if absent)
• Env override: SPELUNK_PROJECT_ID

Project slug for the spelunk-server (e.g. acme/my-app). Required when server_url is set and points at a non-loopback address. Set this in .spelunk/config.toml (project-level) or via SPELUNK_PROJECT_ID.

If server_url is a loopback address (127.0.0.1, localhost, ::1), project_id may be omitted: spelunk derives a stable id from the project's git remote (host/owner/repo), or from a hash of the local path if there's no git remote.

plans_dir

• Type: path (relative to project root)
• Default: docs/plans

Directory where spelunk plan create writes plan files.

specs_dir

• Type: path (relative to project root)
• Default: docs/specs

Directory where spec markdown files are discovered during spelunk index and where spelunk spec looks for spec files.

llm_context_length

• Type: integer
• Default: 8192

Context-window size (tokens) of the configured LLM, used for spelunk memory harvest and spelunk explore. spelunk uses this to split harvest batches that would overflow the model's window. Set this to match the n_ctx / context-length of the model you have loaded.

store_in_git_notes

• Type: boolean
• Default: true

When true, spelunk memory add also appends the new entry as a line of JSON to refs/notes/spelunk on HEAD. This keeps memory close to commits, so it travels with the code. Failure to write the git note is non-fatal: a warning is logged and the primary SQLite write is unaffected. Set store_in_git_notes = false to opt out.

.spelunk/config.toml (project-level) — example

Safe to commit; contains no secrets.

# .spelunk/config.toml
server_url = "http://spelunk.internal:7777"
project_id = "my-awesome-app"

Only server_url, server_key, project_id, and their deprecated aliases (memory_server_url, memory_server_key) are read from this file. Other fields belong in the personal config.

~/.config/spelunk/config.toml (personal) — example

# ~/.config/spelunk/config.toml

# Point at your own OpenAI-compatible endpoint instead of the native embedder
api_base_url = "http://127.0.0.1:1234"
embedding_model = "text-embedding-embeddinggemma-300m-qat"
batch_size = 32

# Enable spelunk explore / memory harvest
llm_model = "google/gemma-3n-e4b"
llm_context_length = 8192

# Team server credentials (do not commit)
server_key = "shared-team-key"

Environment variable overrides

What's next

• Server setup — server_url / server_key in a team deployment
• Memory guide — store_in_git_notes and memory backends
• CLI reference — -c, --config and per-command overrides