Configuration Reference

Complete reference for OpenGround configuration options

Complete reference for all OpenGround configuration options. Configuration is stored in ~/.openground/config.json.

Configuration File

Location: ~/.openground/config.json

Access:

openground config path  # Show path
openground config show  # Show current config

Top-Level Keys

db_path

db_path · string · default: "~/.openground/lancedb"

Path to the LanceDB database directory. Stores vector embeddings and metadata.

Example:

openground config set db_path /custom/path/lancedb

table_name

table_name · string · default: "documents"

Name of the LanceDB table for storing documents.

Example:

openground config set table_name my_documents

raw_data_dir

raw_data_dir · string · default: "~/.openground/raw_data"

Directory for storing extracted documentation (JSON files) before embedding.

Structure: {raw_data_dir}/{library}/{version}/page_*.json

Example:

openground config set raw_data_dir /mnt/data/openground/raw

embeddings

Embedding and chunking configuration.

embeddings.embedding_backend

embeddings.embedding_backend · string · default: "fastembed"

Embedding backend to use.

Valid values:

• sentence-transformers - Full transformers library (GPU/MPS/CPU support)
• fastembed - Lightweight, optimized for CPU speed (default)

Validation: Must be one of these two values.

Example:

openground config set embeddings.embedding_backend sentence-transformers

embeddings.embedding_model

embeddings.embedding_model · string · default: "BAAI/bge-small-en-v1.5"

Name of the embedding model to use.

Default: BAAI/bge-small-en-v1.5 (384 dimensions, optimized for quality/speed balance)

Other models:

• BAAI/bge-base-en-v1.5 (768 dimensions, higher quality)
• sentence-transformers/all-MiniLM-L6-v2 (384 dimensions, faster)
• all-mpnet-base-v2 (768 dimensions, best quality, sentence-transformers only)

Note: Changing this requires re-embedding all libraries.

Example:

openground config set embeddings.embedding_model BAAI/bge-base-en-v1.5

embeddings.embedding_dimensions

embeddings.embedding_dimensions · integer · default: "384"

Dimension of the embedding vectors. Must match the model’s output dimensions.

Common dimensions:

• 384 - BAAI/bge-small-en-v1.5 (default), all-MiniLM-L6-v2
• 768 - BAAI/bge-base-en-v1.5, all-mpnet-base-v2

Note: This must match your model’s dimensions. Changing this requires re-embedding.

Example:

openground config set embeddings.embedding_dimensions 768

embeddings.batch_size

embeddings.batch_size · integer · default: "32"

Number of chunks to process in a single batch when generating embeddings.

Trade-offs:

• Larger batches (64-128): Faster on GPU, more memory usage
• Smaller batches (8-16): Lower memory usage, slower processing

Recommended: 32 for most systems, increase if you have lots of GPU memory

Example:

openground config set embeddings.batch_size 64

embeddings.chunk_size

embeddings.chunk_size · integer · default: "800"

Maximum size of text chunks (in characters) for embedding.

Trade-offs:

• Smaller chunks (256-512): More granular, better for specific queries
• Larger chunks (1024-2048): More context, better for broad topics

Recommended range: 256 - 2048

Example:

openground config set embeddings.chunk_size 1024

embeddings.chunk_overlap

embeddings.chunk_overlap · integer · default: "200"

Number of overlapping characters between consecutive chunks.

Purpose: Prevents information loss at chunk boundaries.

Recommended: 20-25% of chunk_size (default is 25% of 800)

Example:

openground config set embeddings.chunk_overlap 256

query

Search and query configuration.

query.top_k

query.top_k · integer · default: "5"

Number of results to return from queries by default.

Can be overridden: Using --top-k flag in openground query

Recommended range: 3 - 20

Example:

openground config set query.top_k 10

extraction

Extraction and scraping configuration.

extraction.concurrency_limit

extraction.concurrency_limit · integer · default: "50"

Maximum number of concurrent requests when extracting from sitemaps.

Trade-offs:

• Higher values: Faster extraction, more memory/bandwidth
• Lower values: Slower extraction, less resource usage

Recommended range: 5 - 50

Example:

openground config set extraction.concurrency_limit 20

sources

Source management configuration.

sources.auto_add_local

sources.auto_add_local · boolean · default: "true"

Automatically add sources to ~/.openground/sources.json when using openground add with --source flag.

When enabled: Source configs are saved for future use

When disabled: Must provide --source every time

Example:

openground config set sources.auto_add_local false

sources.file_path

sources.file_path · string · default: "~/.openground/sources.json"

Path to the sources configuration file.

Use case: Custom location for source definitions

Example:

openground config set sources.file_path /custom/sources.json

Example Configuration

{
  "db_path": "~/.openground/lancedb",
  "table_name": "documents",
  "raw_data_dir": "~/.openground/raw_data",
  "embeddings": {
    "embedding_backend": "sentence-transformers",
    "model_name": "all-MiniLM-L6-v2",
    "chunk_size": 512,
    "chunk_overlap": 128
  },
  "query": {
    "top_k": 5
  },
  "extraction": {
    "concurrency_limit": 10
  },
  "sources": {
    "auto_add_local": true,
    "file_path": "~/.openground/sources.json"
  }
}

Common Configurations

High-Quality Embeddings

Better semantic understanding, slower, more disk space:

openground config set embeddings.model_name all-mpnet-base-v2
openground config set embeddings.chunk_size 1024
openground config set embeddings.chunk_overlap 256

Fast and Lightweight

Faster extraction and queries, less disk space:

openground config set embeddings.embedding_backend fastembed
openground config set embeddings.model_name BAAI/bge-small-en-v1.5
openground config set extraction.concurrency_limit 20

Large Context

Better for documentation with long-form content:

openground config set embeddings.chunk_size 2048
openground config set embeddings.chunk_overlap 512
openground config set query.top_k 3

Detailed Queries

More results, better for exploration:

openground config set query.top_k 15
openground config set embeddings.chunk_size 256

Changing Settings

View Current Value

openground config get embeddings.chunk_size

Change a Value

openground config set embeddings.chunk_size 1024

Reset to Defaults

openground config reset

When Changes Take Effect

Setting	Takes Effect
db_path, table_name, raw_data_dir	Immediately (affects new operations)
embeddings.*	Requires re-embedding existing libraries
query.top_k	Immediately (or use --top-k flag)
extraction.concurrency_limit	Next extraction
sources.*	Immediately

Re-embedding After Embedding Changes

If you change embedding settings, you must re-embed:

# Delete old embeddings
openground nuke embeddings -y

# Re-embed all libraries
for lib in $(openground list-raw-libraries | awk '{print $1}' | tail -n +2); do
  openground embed $lib
done

Related Commands

• openground config - Manage configuration
• openground nuke - Delete data when changing embeddings
• openground add - Add documentation