How to Configure Code-Graph-RAG Using Environment Variables

Code-Graph-RAG loads all runtime settings from environment variables via a Pydantic-based AppConfig class defined in 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. 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:

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

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

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

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 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 (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 (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}