configuration.md

Configuration Reference

Complete reference for all configuration options. One schema (src/config-schema.ts) defines every key, its default, its validation, and its environment variable. Keys renamed in 2.0 are listed in the migration guide.

Config File Locations

Location	Holds	Precedence
Environment variables	Any key	Highest
~/.libscope/secrets.json	API keys only
.libscope.json (project root)	Non-secret keys
~/.libscope/config.json	Non-secret keys
Built-in defaults	—	Lowest

API keys are read only from environment variables and ~/.libscope/secrets.json (mode 0600). An API key in config.json or .libscope.json is ignored, and LibScope logs a warning.

A value in a config file that fails validation is ignored with a warning, and the next layer applies. An environment variable with an invalid value is also ignored with a warning.

All Config Keys

Every key section.field has the environment variable LIBSCOPE_<SECTION>_<FIELD> (for example embedding.model → LIBSCOPE_EMBEDDING_MODEL). This table is generated from the schema (npm run docs:gen).

Key	Type	Default	Environment variables	Secret	Description
embedding.provider	local | ollama | openai	local	LIBSCOPE_EMBEDDING_PROVIDER		Embedding provider.
embedding.model	string	ollama: nomic-embed-text; openai: text-embedding-3-small	LIBSCOPE_EMBEDDING_MODEL		Embedding model. Ignored by the local provider (always sentence-transformers/all-MiniLM-L6-v2).
embedding.url	string	http://localhost:11434	LIBSCOPE_EMBEDDING_URL		Server URL of the embedding provider. Used by the ollama provider.
embedding.dimensions	integer	size of the model	LIBSCOPE_EMBEDDING_DIMENSIONS		Vector size, for models whose size is not built in.
llm.provider	auto | openai | anthropic | ollama | passthrough	auto	LIBSCOPE_LLM_PROVIDER		LLM for "ask". "auto": passthrough under MCP, else openai if an OpenAI key is set, else anthropic if an Anthropic key is set, else ollama if llm.url is set or embedding.provider is ollama, else none.
llm.model	string	openai: gpt-4o-mini; anthropic: claude-3-5-haiku-20241022; ollama: llama3.2	LIBSCOPE_LLM_MODEL		LLM model.
llm.url	string	embedding.url, then http://localhost:11434	LIBSCOPE_LLM_URL		Server URL of the LLM. Used by the ollama provider.
openai.apiKey	string	—	LIBSCOPE_OPENAI_API_KEY, OPENAI_API_KEY	yes	OpenAI API key (embeddings and LLM).
anthropic.apiKey	string	—	LIBSCOPE_ANTHROPIC_API_KEY, ANTHROPIC_API_KEY	yes	Anthropic API key (LLM).
database.path	string	~/.libscope/workspaces/<workspace>/libscope.db	LIBSCOPE_DATABASE_PATH		SQLite database file. A leading ~ is expanded. Unset: the workspace database.
indexing.maxDocumentSize	integer	104857600	LIBSCOPE_INDEXING_MAX_DOCUMENT_SIZE		Largest document to index, in bytes.
indexing.allowPrivateUrls	boolean	false	LIBSCOPE_INDEXING_ALLOW_PRIVATE_URLS		Allow fetching URLs on private or local networks.
indexing.allowSelfSignedCerts	boolean	false	LIBSCOPE_INDEXING_ALLOW_SELF_SIGNED_CERTS		Accept self-signed TLS certificates when fetching.
logging.level	debug | info | warn | error | silent	info	LIBSCOPE_LOGGING_LEVEL		Log level.
mcp.toolsets	list of core | admin | all	none	LIBSCOPE_MCP_TOOLSETS		Optional MCP toolsets (comma list). admin adds sync, install-pack, list-packs and reindex-documents; all enables every optional toolset. The core tools are always on.

Notes:

• embedding.dimensions is needed only for Ollama or OpenAI models whose vector size LibScope does not know. For text-embedding-3-*, it also requests shorter vectors. After you change the embedding provider, model or dimensions, run libscope admin reindex --rebuild.
• llm.provider: see Automatic LLM selection.
• Each API key is read in this order: LIBSCOPE_<PROVIDER>_API_KEY, then <PROVIDER>_API_KEY, then ~/.libscope/secrets.json. libscope config set openai.apiKey <key> writes the key to secrets.json, never to config.json. libscope config show and libscope config get mask keys (for example sk-…abcd).
• Booleans accept true, false, 1 and 0 in environment variables and in config set.
• A list key (mcp.toolsets) accepts a JSON array in a config file, or a comma-separated list in a config file, an environment variable, and config set (for example libscope config set mcp.toolsets admin).

Automatic LLM selection

When llm.provider is auto (the default), LibScope selects the LLM when ask runs. It does not make network calls to decide:

1. Under the MCP server: passthrough. The calling assistant writes the answer from the retrieved context.
2. Otherwise, openai if an OpenAI key is set.
3. Otherwise, anthropic if an Anthropic key is set.
4. Otherwise, ollama if llm.url is set or embedding.provider is ollama.
5. Otherwise there is no LLM. ask fails with a message that tells you which key or setting to add.

Set llm.provider to a specific provider to skip this selection.

Other Environment Variables

These variables are not config keys:

Variable	Description	Default
LIBSCOPE_WORKSPACE	Active workspace (overrides libscope workspace use)	default
LIBSCOPE_API_KEY	REST API key. When set, requests must send Authorization: Bearer <key>	—
LIBSCOPE_SECRET_KEY	Key used to encrypt stored webhook secrets	—
LIBSCOPE_VERBOSE	1 turns on debug logs (JSON, on stderr) in the CLI	—
LIBSCOPE_GIT_TIMEOUT_MS	Timeout of each git call made for pack registries, in milliseconds (at most 300000)	60000

Connector credentials are not read from environment variables. Give them to libscope connect <type> (see Connectors).

LibScope does not load .env files. Export variables in your shell, or set them in the env block of your MCP client config.

Setting Values

# Embedding
libscope config set embedding.provider ollama      # local | ollama | openai
libscope config set embedding.url http://localhost:11434
libscope config set embedding.model nomic-embed-text

# LLM (for RAG)
libscope config set llm.provider openai            # auto | openai | anthropic | ollama | passthrough
libscope config set llm.model gpt-4o-mini

# API keys (written to ~/.libscope/secrets.json)
libscope config set openai.apiKey sk-...
libscope config set anthropic.apiKey sk-ant-...

# Database
libscope config set database.path ~/kb/libscope.db   # overrides the workspace database
libscope config unset database.path                   # back to the workspace database

# Logging
libscope config set logging.level debug            # debug | info | warn | error | silent

# Network
libscope config set indexing.allowPrivateUrls true
libscope config set indexing.allowSelfSignedCerts true

# Size limit (bytes)
libscope config set indexing.maxDocumentSize 52428800

# MCP server: enable the admin toolset
libscope config set mcp.toolsets admin

# Read, remove, and locate
libscope config get embedding.provider             # effective value (API keys masked)
libscope config unset llm.model                    # remove from the file that holds the key
libscope config path                               # print the user config file path

# View current config (API keys masked)
libscope config show

config set accepts every key in All Config Keys. It checks the value type (booleans accept true/false/1/0, integers must be positive, and enum keys must use a listed value). It writes only the key you set and keeps all other content of the file, including registries. API keys go to ~/.libscope/secrets.json. All other keys go to ~/.libscope/config.json. Both files are written with mode 0600.

Corporate / Internal Networks

If you're indexing docs from internal servers (Confluence, wikis, etc.):

# Allow fetching from private/internal IP addresses
libscope config set indexing.allowPrivateUrls true

# Accept self-signed or corporate TLS certificates
libscope config set indexing.allowSelfSignedCerts true

Example Config File

{
  "embedding": {
    "provider": "ollama",
    "url": "http://localhost:11434",
    "model": "nomic-embed-text"
  },
  "llm": {
    "provider": "openai",
    "model": "gpt-4o-mini"
  },
  "logging": {
    "level": "info"
  },
  "indexing": {
    "allowPrivateUrls": false,
    "allowSelfSignedCerts": false
  }
}