# Configuring Code-Graph-RAG Using Settings and Environment Variables

> Learn to configure Code-Graph-RAG using environment variables and .env files. Easily manage your runtime settings for seamless integration and operation. Get started today!

- Repository: [Vitali Avagyan/code-graph-rag](https://github.com/vitali87/code-graph-rag)
- Tags: how-to-guide
- Published: 2026-08-15

---

**Code‑Graph‑RAG reads all runtime configuration from environment variables (or a `.env` file) parsed through the `AppConfig` class in [`codebase_rag/config.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py).**

This open-source repository by **vitali87/code-graph-rag** uses **pydantic-settings** to centralize every tunable parameter—from graph database connection details to API keys and security policies—making system behavior predictable and version-controllable.

## How Configuration Loading Works

The configuration flow follows a strict three-stage pipeline implemented in [`codebase_rag/config.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py):

1. **Dotenv loading** – `load_dotenv()` executes at import time (line 20), pulling variables from `.env` into `os.environ`.
2. **Pydantic validation** – `AppConfig(BaseSettings)` instantiates once as `settings = AppConfig()` (lines 46–47), reading from environment variables with case-insensitive matching.
3. **System-wide access** – Any module imports `settings` from `codebase_rag.config` and accesses typed attributes directly.

The `SettingsConfigDict` (lines 52–56) explicitly configures:

```python
SettingsConfigDict(
    env_file=".env",
    env_file_encoding="utf-8",
    case_sensitive=False
)

```

## Core Configuration Variables

All settings are declared as fields on `AppConfig` with sensible defaults. When a variable is omitted, the system uses the hard-coded default from the field definition.

### Database Connection

| Variable | Default | Purpose |
|----------|---------|---------|
| `MEMGRAPH_HOST` | `localhost` | Hostname for the Memgraph graph database |
| `MEMGRAPH_PORT` | `7687` | Bolt protocol port |
| `MEMGRAPH_USER` | *(none)* | Authentication username |
| `MEMGRAPH_PASSWORD` | *(none)* | Authentication password |

### LLM Orchestrator Settings

The `ORCHESTRATOR_PROVIDER` and `ORCHESTRATOR_MODEL` fields control which LLM handles query planning and response generation. Supported providers are defined in `constants.Provider`.

### Vector Store Backend

`VECTOR_STORE_BACKEND` accepts enum values from `cs.VectorStoreBackend` (lines 79–81), selecting between implementations like `memgraph`, `qdrant`, or `chroma`.

## Provider-Specific API Key Validation

Remote providers require authenticated access. The `ModelConfig.validate_api_key()` method (lines 21–44) enforces this through the `API_KEY_INFO` mapping:

```python
API_KEY_INFO = {
    cs.Provider.OPENAI: "OPENAI_API_KEY",
    cs.Provider.ANTHROPIC: "ANTHROPIC_API_KEY",
    cs.Provider.GOOGLE: "GOOGLE_API_KEY",
    # ...

}

```

If `ORCHESTRATOR_PROVIDER=openai` is set but `OPENAI_API_KEY` is missing, the system raises a clear validation error before any network call occurs.

## Complete Configuration Examples

### Local Ollama Setup (No API Keys Required)

```dotenv

# .env

MEMGRAPH_HOST=localhost
MEMGRAPH_PORT=7687
OLLAMA_BASE_URL=http://localhost:11434
ORCHESTRATOR_PROVIDER=ollama
ORCHESTRATOR_MODEL=llama3.1

```

Ollama is recognized as a **local provider** (`LOCAL_PROVIDERS = {cs.Provider.OLLAMA}`, lines 99–100), bypassing API key checks entirely.

### OpenAI Cloud Setup

```dotenv

# .env

ORCHESTRATOR_PROVIDER=openai
ORCHESTRATOR_MODEL=gpt-4o
OPENAI_API_KEY=sk-XXXXXXXXXXXXXXXXXXXXXXXX

```

### Qdrant Vector Store Configuration

```dotenv

# .env

VECTOR_STORE_BACKEND=qdrant
QDRANT_URL=http://localhost:6333
QDRANT_COLLECTION_NAME=code_embeddings

```

### Security: Shell Command Restrictions

```dotenv

# .env

SHELL_COMMAND_ALLOWLIST=ls,rg,git,python
SHELL_READ_ONLY_COMMANDS=ls,cat,grep

```

Both fields parse as **frozensets** via pydantic. The allowlist restricts which commands the internal sandbox permits; `SHELL_READ_ONLY_COMMANDS` further constrains operations that cannot modify filesystem state.

## Accessing Settings in Python Code

```python
from codebase_rag.config import settings

# Typed attributes with full IDE support

print("Graph host:", settings.MEMGRAPH_HOST)
print("Orchestrator model:", settings.ORCHESTRATOR_MODEL)
print("Embedding backend:", settings.VECTOR_STORE_BACKEND.value)

# Check if running against local LLM

if settings.ORCHESTRATOR_PROVIDER in settings.LOCAL_PROVIDERS:
    print("Using local provider—no API key needed")

```

## Key Source Files

All configuration logic is centralized in these locations:

- **[`codebase_rag/config.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py)** – `AppConfig` definition, `load_dotenv()` call, `API_KEY_INFO` mapping, and all environment variable declarations.
- **`.env.example`** – Exhaustive reference of every supported variable with placeholder values.
- **[`codebase_rag/models.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/models.py)** – `ModelConfig` dataclass containing provider-specific validation logic.
- **[`codebase_rag/constants.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/constants.py)** – Enum definitions for `Provider`, `VectorStoreBackend`, and other typed configuration values.

## Extending the Configuration System

To add a new environment variable:

1. Add a typed field to `AppConfig` with an appropriate default (or `None` for required values).
2. If provider-specific, add the key mapping to `API_KEY_INFO`.
3. Update `.env.example` with documentation.

This pattern keeps the configuration **self-documenting** and ensures consistent error messaging across the codebase.

## Summary

- **All settings** in vitali87/code-graph-rAG derive from environment variables loaded via `python-dotenv` and validated through `pydantic-settings`.
- **[`codebase_rag/config.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py)** instantiates a singleton `settings` object that modules import directly.
- **Provider API keys** are enforced automatically through `ModelConfig.validate_api_key()` and the `API_KEY_INFO` registry.
- **Local providers** (Ollama) require no authentication; remote providers fail fast with clear error messages if keys are missing.
- **Security policies** like shell command restrictions are configurable through frozenset-parsed environment variables.

## Frequently Asked Questions

### What happens if I don't create a `.env` file?

The system falls back to hard-coded defaults defined in `AppConfig` fields. For local development with Memgraph and Ollama on standard ports, no `.env` file is required—`localhost` defaults apply.

### How do I switch from Ollama to OpenAI without code changes?

Set `ORCHESTRATOR_PROVIDER=openai` and `OPENAI_API_KEY=sk-...` in your `.env` file, then restart the application. The `AppConfig` model re-reads environment variables on every import.

### Can I use multiple vector store backends simultaneously?

No—the `VECTOR_STORE_BACKEND` field accepts a single `VectorStoreBackend` enum value. The system instantiates one backend at startup based on this selection.

### Where should I add a new environment variable for a custom feature?

Add it to `AppConfig` in [`codebase_rag/config.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py) with a type annotation and default value. If it controls model behavior, consider adding validation logic in [`codebase_rag/models.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/models.py).