> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/poweroutlet2/openground/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:**

```bash theme={null}
openground config path  # Show path
openground config show  # Show current config
```

## Top-Level Keys

### db\_path

<ParamField path="db_path" type="string" default="~/.openground/lancedb">
  Path to the LanceDB database directory. Stores vector embeddings and metadata.

  **Example:**

  ```bash theme={null}
  openground config set db_path /custom/path/lancedb
  ```
</ParamField>

### table\_name

<ParamField path="table_name" type="string" default="documents">
  Name of the LanceDB table for storing documents.

  **Example:**

  ```bash theme={null}
  openground config set table_name my_documents
  ```
</ParamField>

### raw\_data\_dir

<ParamField path="raw_data_dir" type="string" default="~/.openground/raw_data">
  Directory for storing extracted documentation (JSON files) before embedding.

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

  **Example:**

  ```bash theme={null}
  openground config set raw_data_dir /mnt/data/openground/raw
  ```
</ParamField>

## embeddings

Embedding and chunking configuration.

### embeddings.embedding\_backend

<ParamField path="embeddings.embedding_backend" type="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:**

  ```bash theme={null}
  openground config set embeddings.embedding_backend sentence-transformers
  ```
</ParamField>

### embeddings.embedding\_model

<ParamField path="embeddings.embedding_model" type="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:**

  ```bash theme={null}
  openground config set embeddings.embedding_model BAAI/bge-base-en-v1.5
  ```
</ParamField>

### embeddings.embedding\_dimensions

<ParamField path="embeddings.embedding_dimensions" type="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:**

  ```bash theme={null}
  openground config set embeddings.embedding_dimensions 768
  ```
</ParamField>

### embeddings.batch\_size

<ParamField path="embeddings.batch_size" type="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:**

  ```bash theme={null}
  openground config set embeddings.batch_size 64
  ```
</ParamField>

### embeddings.chunk\_size

<ParamField path="embeddings.chunk_size" type="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:**

  ```bash theme={null}
  openground config set embeddings.chunk_size 1024
  ```
</ParamField>

### embeddings.chunk\_overlap

<ParamField path="embeddings.chunk_overlap" type="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:**

  ```bash theme={null}
  openground config set embeddings.chunk_overlap 256
  ```
</ParamField>

## query

Search and query configuration.

### query.top\_k

<ParamField path="query.top_k" type="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:**

  ```bash theme={null}
  openground config set query.top_k 10
  ```
</ParamField>

## extraction

Extraction and scraping configuration.

### extraction.concurrency\_limit

<ParamField path="extraction.concurrency_limit" type="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:**

  ```bash theme={null}
  openground config set extraction.concurrency_limit 20
  ```
</ParamField>

## sources

Source management configuration.

### sources.auto\_add\_local

<ParamField path="sources.auto_add_local" type="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:**

  ```bash theme={null}
  openground config set sources.auto_add_local false
  ```
</ParamField>

### sources.file\_path

<ParamField path="sources.file_path" type="string" default="~/.openground/sources.json">
  Path to the sources configuration file.

  **Use case:** Custom location for source definitions

  **Example:**

  ```bash theme={null}
  openground config set sources.file_path /custom/sources.json
  ```
</ParamField>

## Example Configuration

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
openground config set query.top_k 15
openground config set embeddings.chunk_size 256
```

## Changing Settings

### View Current Value

```bash theme={null}
openground config get embeddings.chunk_size
```

### Change a Value

```bash theme={null}
openground config set embeddings.chunk_size 1024
```

### Reset to Defaults

```bash theme={null}
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:

```bash theme={null}
# 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](/cli/config) - Manage configuration
* [openground nuke](/cli/nuke) - Delete data when changing embeddings
* [openground add](/cli/add) - Add documentation