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

# Configuration

> Understand where defaults live for the SDK, CLI, and REST API.

Ragrails has three interfaces, and each one gets defaults from a different place. Keeping those scopes separate prevents most configuration surprises.

| Interface | Where defaults live                               | How to override                 |
| --------- | ------------------------------------------------- | ------------------------------- |
| SDK       | The `RagRails(...)` object you create in Python   | Pass arguments to a method call |
| CLI       | `.ragrails.toml` in the current working directory | Pass command flags              |
| REST API  | Each JSON request body                            | Send different request fields   |

See [vector databases](/reference/vector-databases) for supported `provider` / `vector_db` values.

<Warning>SDK constructor defaults do not automatically become CLI defaults. CLI `.ragrails.toml` values do not automatically become REST defaults.</Warning>

## One Stack, Three Config Forms

This is the same local setup in each interface: Qdrant at `http://localhost:6333`, Voyage embeddings, and OpenAI chat.

<CodeGroup>
  ```python SDK theme={null}
  from ragrails import RagRails

  rag = RagRails(
      collection="support",
      vector_store={"provider": "qdrant", "url": "http://localhost:6333"},
      embedding={"provider": "voyage", "model": "voyage-3"},
      llm={"provider": "openai", "model": "gpt-4o-mini"},
  )
  ```

  ```toml CLI theme={null}
  # .ragrails.toml
  [vector_store]
  provider = "qdrant"
  collection = "support"
  url = "http://localhost:6333"

  [embedding]
  provider = "voyage"
  model = "voyage-3"

  [llm]
  provider = "openai"
  model = "gpt-4o-mini"
  max_tokens = 1024
  ```

  ```json REST API theme={null}
  {
    "embedding": {"provider": "voyage", "model": "voyage-3"},
    "storage": {"vector_db": "qdrant", "collection": "support", "url": "http://localhost:6333"},
    "retrieval": {"vector_db": "qdrant", "collection": "support", "url": "http://localhost:6333"},
    "llm_provider": "openai",
    "llm_model": "gpt-4o-mini"
  }
  ```
</CodeGroup>

## SDK Defaults

Use constructor defaults when you are writing Python. Every call on that `rag` object can inherit the configured vector store, embedding model, LLM, and reranker.

```python theme={null}
from ragrails import RagRails

rag = RagRails(
    collection="support",
    vector_store={"provider": "qdrant", "url": "http://localhost:6333"},
    embedding={"provider": "voyage", "model": "voyage-3"},
    llm={"provider": "openai", "model": "gpt-4o-mini"},
)

rag.ingest(markdown="# Refund policy\n\nRefunds are available within 30 days.")
rag.chat("How long do I have to request a refund?", history=[])
```

Override one call by passing method arguments:

```python theme={null}
rag.query("refund window", retrieval={"top_k": 5})
rag.chat("Summarize it", llm=rag.llm(model="gpt-4o"), history=[])
```

<Note>`rag.llm()` requires a model unless one was configured in `RagRails(llm={...})`.</Note>

## CLI Defaults

Use `.ragrails.toml` when you run terminal commands. The CLI looks for `.ragrails.toml` in the current working directory.

Run `ragrails` with no subcommand to open the setup wizard:

```bash theme={null}
ragrails
```

The wizard writes `.ragrails.toml`. After that, commands can be shorter:

```bash theme={null}
ragrails ingest --markdown "# Refund policy\n\nRefunds are available within 30 days."
ragrails query "How long do I have to request a refund?"
ragrails chat "How long do I have to request a refund?"
```

Without `.ragrails.toml`, pass explicit flags:

```bash theme={null}
ragrails query "How long do I have to request a refund?" \
  --vector-db qdrant --collection support --url http://localhost:6333 \
  --provider voyage --model voyage-3 --top-k 5
```

Flags always win for that run. For example, this queries a different collection without editing `.ragrails.toml`:

```bash theme={null}
ragrails query "refund policy" --collection legal
```

## REST API Defaults

REST requests are self-contained. Put provider and vector-store settings in the request body.

```bash theme={null}
curl -X POST http://127.0.0.1:8000/v1/pipelines/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How long do I have to request a refund?",
    "embedding": {"provider": "voyage", "model": "voyage-3"},
    "retrieval": {"vector_db": "qdrant", "collection": "support", "url": "http://localhost:6333", "top_k": 5}
  }'
```

The REST API also exposes `/docs` and `/v1/openapi.json`, so generated clients can type these request bodies.

## Secrets

Do not put API keys in `.ragrails.toml`. Store non-secret defaults in config and keep credentials in environment variables.

```bash theme={null}
export VOYAGE_API_KEY="..."
export OPENAI_API_KEY="..."
export QDRANT_API_KEY="..."  # Qdrant Cloud only
```

See [environment variables](/getting-started/env-examples) for every provider key.

## Complete `.ragrails.toml`

Keep only the sections you need.

```toml theme={null}
[vector_store]
provider = "qdrant"          # qdrant, qdrant_cloud, pinecone, weaviate
collection = "support"
url = "http://localhost:6333"

[embedding]
provider = "voyage"
model = "voyage-3"
batch_size = 64

[llm]
provider = "openai"          # openai, anthropic, google
model = "gpt-4o-mini"
max_tokens = 1024

[reranker]
enabled = false
provider = "voyage"
model = "rerank-2-lite"

[chunking]
chunk_size = 2000
chunk_overlap = 200
min_chunk_length = 100

[storage]
batch_size = 64

[retrieval]
top_k = 10
rerank_top_k = 5

[chat]
query_rewrite = false
intent_routing = true
history_compaction = true
```

## Validate CLI Config

Run `doctor` from the same directory as `.ragrails.toml`:

```bash theme={null}
ragrails doctor
```

Use `--config` to inspect a file somewhere else:

```bash theme={null}
ragrails doctor --config path/to/.ragrails.toml
```

## URL Ingestion Setup

Scrape Website needs the URL extra and a browser install. This is environment setup, not provider configuration.

<CodeGroup>
  ```python SDK theme={null}
  rag.setup_url()
  ```

  ```bash CLI theme={null}
  pip install "ragrails[url]"
  ragrails setup-url
  ```

  ```bash REST API theme={null}
  # Install the URL extra in the server environment before starting ragrails-api.
  pip install "ragrails[url,server-qdrant]"
  ```
</CodeGroup>