# How to Configure Code-Graph-RAG Using Environment Variables

> Learn to configure Code-Graph-RAG using environment variables. Discover how Pydantic and .env files streamline runtime settings for your codebase RAG application.

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

---

**Code-Graph-RAG loads all runtime settings from environment variables via a Pydantic-based `AppConfig` class defined in [`codebase_rag/config.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py), supporting both `.env` files and direct environment injection.**

The `vitali87/code-graph-rag` repository centralizes its configuration system through environment variables, making it easy to switch between local and cloud providers without modifying source code. Understanding how to configure Code-Graph-RAG using environment variables ensures secure credential management and flexible deployment across development and production environments.

## Configuration Architecture

The configuration flow follows a strict import-time sequence in [`codebase_rag/config.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py). When the module loads, `load_dotenv()` from *python-dotenv* immediately reads a `.env` file into `os.environ` (line 20). Subsequently, the `AppConfig` class—a **Pydantic Settings** (`BaseSettings`) subclass—parses these variables and exposes them as type-safe attributes.

### The AppConfig Model

The `AppConfig` model (lines 46-47) declares every supported environment variable as a typed field with sensible defaults. Using `SettingsConfigDict` (lines 52-56), Pydantic configures case-insensitive parsing and UTF-8 encoding for the `.env` file. This design pattern ensures that `settings = AppConfig()` becomes the single source of truth for the entire application.

### Provider API Key Validation

For remote LLM providers, `ModelConfig.validate_api_key()` (lines 21-44) enforces presence of required credentials. The mapping `API_KEY_INFO` (lines 29-34) associates each provider with its expected environment variable name (e.g., `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`), raising clear errors before runtime if keys are missing.

## Essential Environment Variables

### Graph Database Connection

Configure Memgraph connection parameters using standard environment variables:

- `MEMGRAPH_HOST` – Database hostname (default: `localhost`)
- `MEMGRAPH_PORT` – Bolt protocol port (default: `7687`)
- `MEMGRAPH_USER` / `MEMGRAPH_PASSWORD` – Authentication credentials

### LLM Provider Configuration

The orchestrator layer selects providers via enum values:

- `ORCHESTRATOR_PROVIDER` – One of `openai`, `anthropic`, `ollama`, or `google`
- `ORCHESTRATOR_MODEL` – Specific model identifier (e.g., `gpt-4o`, `llama3.1`)

For **local providers** like Ollama, defined in `LOCAL_PROVIDERS = {cs.Provider.OLLAMA}` (lines 99-100), no API key is required. Cloud providers require their respective `*_API_KEY` variables.

### Vector Store Backend

Switch embedding storage via `VECTOR_STORE_BACKEND`, a **Pydantic enum** (`cs.VectorStoreBackend`) selecting between implementations (lines 79-81). Supported values include:

- `memgraph` – Native graph embeddings
- `qdrant` – External Qdrant vector database

When using Qdrant, additional variables include `QDRANT_URL` and `QDRANT_COLLECTION_NAME`.

### Security Settings

Sandboxed shell execution respects two frozenset fields:

- `SHELL_COMMAND_ALLOWLIST` – Comma-separated commands permitted for execution
- `SHELL_READ_ONLY_COMMANDS` – Subset restricted to read-only operations

## Configuration Examples

### Local Ollama Setup

For fully local inference without API keys:

```dotenv

# .env

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

```

These variables target a local Ollama instance at port 11434, bypassing the API key validation because Ollama is registered in `LOCAL_PROVIDERS`.

### OpenAI Cloud Setup

For GPT-4o orchestration:

```dotenv

# .env

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

```

When `ORCHESTRATOR_PROVIDER=openai`, the system automatically checks for `OPENAI_API_KEY` via `ModelConfig.validate_api_key()` and fails fast with a descriptive error if absent.

### Qdrant Vector Store

To offload embeddings to Qdrant:

```dotenv

# .env

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

```

The enum validation ensures only supported backends are instantiated.

## Accessing Configuration in Python

Any module can import the singleton settings object:

```python
from codebase_rag.config import settings

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

```

This approach guarantees consistent configuration state across the codebase without re-parsing environment variables.

## Summary

- **Centralized config**: All settings reside in [`codebase_rag/config.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py) as Pydantic fields.
- **Dotenv support**: Variables load automatically from a `.env` file at project root via `load_dotenv()`.
- **Type safety**: The `AppConfig` class validates types and enums (like `VectorStoreBackend`) at startup.
- **Provider validation**: `ModelConfig.validate_api_key()` ensures API keys exist for cloud providers before instantiation.
- **Security controls**: Shell execution limits are configurable via `SHELL_COMMAND_ALLOWLIST` and `SHELL_READ_ONLY_COMMANDS`.

## Frequently Asked Questions

### What file should I create to store environment variables?

Create a `.env` file in the project root directory. The `load_dotenv()` call in [`codebase_rag/config.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py) (line 20) automatically reads this file at import time, populating `os.environ` before `AppConfig` parses the values.

### Why does Code-Graph-RAG require Pydantic Settings instead of os.environ directly?

Using `BaseSettings` from Pydantic provides type coercion, validation, and default value management. The `SettingsConfigDict` configuration (lines 52-56) also enables case-insensitive variable names and automatic `.env` file parsing, reducing boilerplate and preventing runtime type errors.

### How do I add support for a new LLM provider?

Add the provider to the `API_KEY_INFO` mapping in [`codebase_rag/config.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py) (lines 29-34) with its required environment variable name. If the provider is local-only, add it to the `LOCAL_PROVIDERS` frozenset (lines 99-100) to skip API key validation. Then declare any provider-specific configuration fields as new attributes on the `AppConfig` class.

### Can I override settings without a .env file?

Yes. Since `AppConfig` reads from `os.environ`, you can export variables directly in your shell (e.g., `export OPENAI_API_KEY=sk-...`) before launching the application. The system reads the live environment, making it compatible with Docker secrets, Kubernetes ConfigMaps, and CI/CD pipeline variables.