How to Configure Langflow Integration in OpenRAG: Complete Setup Guide

Configure Langflow integration in OpenRAG by setting environment variables like LANGFLOW_URL and flow IDs in your .env file, or use the built-in TUI wizard to auto-generate the configuration.

OpenRAG relies on Langflow as its visual workflow engine to handle document ingestion, retrieval, and chat nudges. The integration is controlled entirely through environment variables read at startup and persisted via the EnvManager located in src/tui/managers/env_manager.py.

Core Configuration Variables

All Langflow settings are defined in src/config/settings.py. At startup, the application loads these variables from the process environment or a .env file via python-dotenv:

LANGFLOW_URL = os.getenv("LANGFLOW_URL", "http://localhost:7860")
LANGFLOW_CHAT_FLOW_ID = os.getenv("LANGFLOW_CHAT_FLOW_ID") or _legacy_flow_id
LANGFLOW_INGEST_FLOW_ID = os.getenv("LANGFLOW_INGEST_FLOW_ID")
LANGFLOW_URL_INGEST_FLOW_ID = os.getenv("LANGFLOW_URL_INGEST_FLOW_ID")
NUDGES_FLOW_ID = os.getenv("NUDGES_FLOW_ID")
LANGFLOW_AUTO_LOGIN = os.getenv("LANGFLOW_AUTO_LOGIN", "False").lower() in ("true","1","yes")

(source: src/config/settings.py lines 27-42)

Required Environment Variables

• LANGFLOW_URL: Base URL of the Langflow HTTP API (default: http://localhost:7860)
• LANGFLOW_CHAT_FLOW_ID: UUID of the retrieval/chat flow created in the Langflow UI
• LANGFLOW_INGEST_FLOW_ID: UUID of the flow that processes uploaded documents
• LANGFLOW_URL_INGEST_FLOW_ID: (Optional) UUID for URL-based ingestion workflows
• NUDGES_FLOW_ID: UUID for the flow generating suggested next steps in the chat UI
• LANGFLOW_AUTO_LOGIN: Set to True to use default super-user credentials (langflow/langflow)
• LANGFLOW_SUPERUSER / LANGFLOW_SUPERUSER_PASSWORD: Custom credentials when auto-login is disabled

Configuration Methods

Using the TUI Wizard

The EnvManager provides an interactive wizard that writes the resolved configuration to a .env file. When you run the TUI, EnvManager.save_env_file() automatically emits the Langflow identifiers and auto-login flags:

# From src/tui/managers/env_manager.py lines 27-40

def save_env_file(self):
    lines = [
        f"LANGFLOW_URL={self.config.langflow_url}",
        f"LANGFLOW_CHAT_FLOW_ID={self.config.chat_flow_id}",
        f"LANGFLOW_INGEST_FLOW_ID={self.config.ingest_flow_id}",
        # ... additional variables

    ]

This approach automatically generates LANGFLOW_SECRET_KEY and other security tokens, eliminating manual editing errors.

Manual .env Configuration

For containerized deployments or CI/CD pipelines, create a .env file manually:

LANGFLOW_URL=http://localhost:7860
LANGFLOW_CHAT_FLOW_ID=1098eea1-6649-4e1d-aed1-b77249fb8dd0
LANGFLOW_INGEST_FLOW_ID=5488df7c-b93f-4f87-a446-b67028bc0813
LANGFLOW_URL_INGEST_FLOW_ID=72c3d17c-2dac-4a73-b48a-6518473d7830
NUDGES_FLOW_ID=ebc01d31-1976-46ce-a385-b0240327226c

LANGFLOW_AUTO_LOGIN=True
LANGFLOW_NEW_USER_IS_ACTIVE=True
LANGFLOW_ENABLE_SUPERUSER_CLI=True

Variables are read once at import time, so modifications require a restart before the first import of config.settings.

Authentication and API Key Generation

If LANGFLOW_KEY is not present in the environment, OpenRAG automatically calls get_langflow_api_key() (defined in src/config/settings.py lines 83-100). This function logs into Langflow using super-user credentials and creates a permanent API key cached in the process environment. Subsequent requests include this key via the x-api-key header.

When LANGFLOW_AUTO_LOGIN is enabled, the system uses the default credentials (langflow/langflow) unless overridden by LANGFLOW_SUPERUSER and LANGFLOW_SUPERUSER_PASSWORD.

Health Checks and Startup Sequence

Before accepting traffic, OpenRAG verifies Langflow availability through the wait_for_langflow coroutine in src/utils/langflow_utils.py (lines 15-30). This function repeatedly calls GET /health on the Langflow HTTP client with exponential backoff until receiving a 200 response or hitting the retry limit.

# Conceptual usage from src/utils/langflow_utils.py

await wait_for_langflow(langflow_http_client=clients.langflow_http_client)

This guarantees that API calls for creating keys or posting chat requests do not fail due to service startup delays.

Runtime Integration

Backend services reference the configured flow IDs to invoke specific Langflow workflows. In src/services/flows_service.py (lines 118-120), the application sends requests using the global clients object:

await self.langflow_request(
    "POST", 
    f"/api/v1/flows/{LANGFLOW_CHAT_FLOW_ID}/run", 
    json=payload
)

Similarly, src/services/chat_service.py (lines 62-64) forwards chat payloads to the flow identified by LANGFLOW_CHAT_FLOW_ID.

Practical Configuration Examples

Minimal Local Development Setup

# OpenRAG Environment Configuration

LANGFLOW_URL=http://localhost:7860
LANGFLOW_CHAT_FLOW_ID=1098eea1-6649-4e1d-aed1-b77249fb8dd0
LANGFLOW_INGEST_FLOW_ID=5488df7c-b93f-4f87-a446-b67028bc0813
LANGFLOW_URL_INGEST_FLOW_ID=72c3d17c-2dac-4a73-b48a-6518473d7830
NUDGES_FLOW_ID=ebc01d31-1976-46ce-a385-b0240327226c

LANGFLOW_AUTO_LOGIN=True

Runtime Override in CI/CD

export LANGFLOW_CHAT_FLOW_ID=abcd1234-ef56-7890-gh12-ijkl3456mnop
export LANGFLOW_INGEST_FLOW_ID=qrst9876-uv12-wxyz-3456-7890abcde123
uv run openrag

Programmatic Health Check

import asyncio
from utils.langflow_utils import wait_for_langflow
from config.settings import clients

async def start():
    await wait_for_langflow(langflow_http_client=clients.langflow_http_client)
    print("Langflow is ready")

asyncio.run(start())

SDK Chat Request

import asyncio
from openrag_sdk import OpenRAGClient

async def chat():
    async with OpenRAGClient() as client:
        response = await client.chat.create(
            message="What is Retrieval-Augmented Generation?"
        )
        print(response.response)

asyncio.run(chat())

The SDK internally uses clients.langflow_request and injects the x-api-key header automatically.

Summary

• Environment variables in src/config/settings.py control all Langflow integration points, including the base URL and specific flow IDs for chat, ingestion, and nudges.
• The EnvManager (src/tui/managers/env_manager.py) provides a TUI wizard that auto-generates and writes the .env file, handling secret keys and credentials.
• Authentication is handled automatically via get_langflow_api_key() when LANGFLOW_AUTO_LOGIN is enabled, creating and caching API keys for the x-api-key header.
• Health checks via wait_for_langflow in src/utils/langflow_utils.py ensure the Langflow container is reachable before OpenRAG services start processing requests.
• Backend services in src/services/flows_service.py and src/services/chat_service.py reference these configuration values to route requests to the correct Langflow workflows.

Frequently Asked Questions

What happens if LANGFLOW_CHAT_FLOW_ID is not set?

OpenRAG will attempt to use a legacy fallback ID if available, but the application will fail to route chat requests properly. According to src/config/settings.py, this variable is required for the chat service to invoke the correct workflow via the Langflow API.

How does OpenRAG handle Langflow authentication automatically?

When LANGFLOW_AUTO_LOGIN is set to True and no LANGFLOW_KEY exists, the system calls get_langflow_api_key() (lines 83-100 in src/config/settings.py) to log in with default super-user credentials and generate a permanent API key. This key is then injected into all subsequent HTTP requests via the x-api-key header.

Can I change Langflow flow IDs without restarting OpenRAG?

No. Environment variables are read once at import time when src/config/settings.py initializes. To apply new flow IDs, you must restart the OpenRAG process after updating the .env file or exporting the new variables.

Why does OpenRAG fail to start even though Langflow is running?

The wait_for_langflow coroutine in src/utils/langflow_utils.py performs a health check against GET /health. If this endpoint returns non-200 status codes or is unreachable due to network configuration, OpenRAG will retry with exponential backoff until the limit is reached. Ensure LANGFLOW_URL points to the correct address and port.

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