The Problem

Enterprises that need reliable, up‑to‑date context for large language models must continuously retrieve, rank, and inject relevant documents while also allowing programmable agent actions. Building that pipeline from scratch requires stitching together vector stores, LLM inference, and sandboxed code execution – a non‑trivial engineering effort.

What This Does

ragflow delivers a full‑stack Retrieval‑Augmented Generation (RAG) engine with an extensible agent layer. The core services live in api/ (REST endpoints) and agent/ (DSL‑driven workflows). Templates such as agent/templates/web_search_assistant.json define reusable agents, while the sandbox (agent/sandbox/) isolates arbitrary code execution. The Go binaries in cmd/ (e.g., cmd/ragflow_server.go) host the HTTP server, and the Python client in admin/client/ provides a thin wrapper for programmatic use.

Key files:

  • cmd/ragflow_server.go – starts the Go server, loads config from conf/, registers API routes.
  • api/channels/whatsapp/gateway-node/index.js – example channel plugin written in Node.
  • agent/component/* – modular components (LLM calls, loops, data ops) that the DSL compiles into executable graphs.
  • Dockerfile* – multi‑stage builds for production and scratch images.

How It Is Wired

  1. Entry point – cmd/ragflow_server.go parses flags, reads conf/config.yaml (not listed but implied by conf/), and creates a server struct.
  2. Server init – admin/server/admin_server.py is imported by the Go server via gRPC (see api/ handlers) to expose admin endpoints.
  3. API routing – api/channels/whatsapp/gateway-node/index.js registers an Express router; other channels follow the same pattern.
  4. RAG pipeline – When a request hits /api/v1/rag, api/ routes forward to agent/component/llm.py (Python) which calls the configured transformer model (via transformers library). Retrieval uses rag/ modules that query the vector store (implementation hidden but referenced from rag/ package).
  5. Agent execution – The DSL parser (agent/dsl_migration.py) builds a graph of component classes (agent/component/*). Execution is driven by agent/component/loop.py and agent/component/iteration.py, which iterate over retrieved chunks.
  6. Sandbox – Any code_exec or browser component hands off to agent/sandbox/executor_manager/main.py. This process runs inside the Docker image defined by agent/sandbox/Dockerfile and is protected by seccomp-profile-default.json. Results travel back through agent/sandbox/result_protocol.py to the calling component.
  7. Response – Final LLM output is assembled in agent/component/message.py and returned to the HTTP layer.

The most critical hub is cmd/ragflow_server.go → api/ → agent/component/ → sandbox. Changing the sandbox image or the component registry has the widest blast radius because many agents depend on it.

How To Use It

# 1. Clone the repo
git clone https://github.com/moses-y/ragflow
cd ragflow

# 2. Build the production Docker image (uses multi‑stage Dockerfile)
docker build -f Dockerfile -t ragflow:latest .

# 3. Run the server (default config expects a PostgreSQL DB and a vector store)
docker run -d \
  -p 80:80 \
  -v $(pwd)/conf:/app/conf \
  --name ragflow ragflow:latest \
  ./cmd/ragflow_server.go   # entry point compiled into the image

If you prefer a local binary:

# Build Go binaries
go build -o bin/ragflow_server ./cmd/ragflow_server.go
go build -o bin/ragflow_cli    ./cmd/ragflow-cli.go

# Start the server
./bin/ragflow_server -c conf/config.yaml

Python client example (requires admin/client/pyproject.toml):

cd admin/client
uv pip install .   # or `pip install -e .`
python -c "from ragflow_client import RagflowClient; \
client = RagflowClient('http://localhost'); print(client.health())"

Configuration files live under conf/ (e.g., conf/private.pem, conf/public.pem for TLS). Environment variables are read by agent/sandbox/.env.example; adapt that file for your deployment.

Real‑World Use

A SaaS product can embed ragflow as a microservice that receives a user query, retrieves relevant support tickets from a PostgreSQL‑backed vector store, runs a “customer‑feedback‑dispatcher” agent (agent/templates/customer_feedback_dispatcher.json), and returns a synthesized answer. The service calls the Go HTTP endpoint, which internally triggers the Python LLM component and sandboxed code to enrich the answer with live data.

Code Health & Issues

  • Low – Secret‑shaped files – conf/private.pem, conf/public.pem, and docker/.env appear in the repo; they may contain production keys.
  • Medium – Mixed language boundaries – Go server calls into Python components via gRPC/HTTP; changes to data contracts require coordination across cmd/, api/, and agent/component/.
  • Low – Test coverage uneven – 1,719 test files exist, but many are under agent/sandbox/tests/; core Go server (cmd/) lacks Go‑level unit tests.
  • Low – CI definition – GitHub Actions workflows (.github/workflows/*.yml) run tests but do not enforce linting or static analysis for Go code.

No critical security findings were automatically detected beyond the secret files noted above.

The Bottom Line

ragflow offers a concrete, container‑ready RAG platform with a programmable agent layer, suitable for teams that need a self‑hosted alternative to managed services. The codebase is large and spans Go, Python, and TypeScript, which adds integration overhead; the presence of private keys in the repository is a clear risk. If you have in‑house expertise across these stacks and can audit the secret files, the project provides a solid foundation for building custom RAG‑driven applications.