Skip to main content
This page answers the questions that come up most often when getting started with Ragen, configuring models, thinking through data privacy, and building integrations. If you don’t find your answer here, check the relevant guide or open an issue on GitHub.

​
Setup & Installation

Run create-ragen-app to scaffold a full local installation in one command:
The wizard clones the repository, generates secrets, asks for a model provider key, starts the backing services in Docker, and runs the first-time database setup. From there, follow the Quickstart to start the apps and create your first account.
To run the full Ragen stack you need:
  • 8 GB of RAM to evaluate it, 16 GB for a small production install — mostly headroom. The containers a default docker compose up starts idle at about 900 MB together, document parsing (Docling) being most of it. What the stack actually costs breaks it down service by service and shows how to run a smaller stack.
  • Docker and Docker Compose
  • Node.js ^24.15.0 || >=26.0.0 if you run the apps outside containers — a range, not a floor
A GPU is only required if you plan to serve language models locally. Everything else runs on CPU.
Yes. Ragen’s architecture supports fully air-gapped operation, but it requires deliberate configuration — it is not a single flag.To run without internet access:
  1. Set all four model variables (DEFAULT_MODEL, REPHRASE_MODEL, SUMMARY_MODEL, EMBEDDINGS_MODEL) to models served on your own hardware via vLLM or Ollama.
  2. Set DOCLING_STRICT=1 to prevent document parsing from falling back to an external model if Docling fails.
  3. Point SMTP_HOST at an internal mail server, or set MAIL_PROVIDER=console to skip email entirely.
  4. After the initial install, serve container images from an internal registry to eliminate outbound traffic for updates.
See Open Models on Your Own Hardware for the full walkthrough, including which model calls still reach outward by default.
Setting only DEFAULT_MODEL to a local model is a common mistake. The REPHRASE_MODEL also defaults to a cloud model and runs on every question. Set all four variables to achieve true isolation.
Pull the latest code and follow the upgrade steps in the release notes:
Then rebuild and restart your services. If you are running the stack via Docker Compose, rebuild the images before restarting containers. Check the GitHub releases page for any migration notes or additional steps required before upgrading.

​
Models & AI

Ragen calls providers itself, using a route table that names the upstream for each model id. Five provider families are built in:
  • OpenAI (GPT-4o, GPT-4.1, o3, etc.)
  • Anthropic (Claude, direct or via Bedrock)
  • Azure OpenAI
  • Amazon Bedrock
  • Google Vertex AI
Anything else that speaks OpenAI’s API — vLLM, Ollama, OpenRouter, Portkey, or a LiteLLM proxy you run yourself — attaches as an openai-compatible route, which is two environment variables and no code change. See Model gateway.
Yes. Ragen uses four separate model roles, each configured independently:Set each variable to a model id that exists in your route table. For example, you might use a fast, cheap model for rephrasing and a more capable one for answering.
You can change it, but doing so requires a full re-index of all existing documents.
A Qdrant collection is created with a fixed vector size at first ingest. Changing EMBEDDINGS_MODEL makes every existing vector incompatible with the new model. You must also update VECTOR_SIZE to match the new model’s output dimensionality, then re-index your entire document corpus.Decide on your embedding model before you ingest anything you would mind re-processing.
Common values for VECTOR_SIZE:
  • bge-multilingual-gemma2 (default) → 3584
  • cohere-embed-multilingual-v3, bge-m3, multilingual-e5-large → 1024
Always verify your specific model’s dimensionality rather than assuming.
Ragen’s default embedding model (bge-multilingual-gemma2) is multilingual. Retrieval uses a hybrid approach — dense vector search for semantic meaning combined with BM25 sparse vectors for exact terms — which performs well across languages and on technical content like part numbers or proper names.The internal benchmark score for multilingual retrieval is 92%. Results for your specific documents and language will vary, so test on your own material before committing to a model.
If your documents are not in English, weigh multilingual ability heavily when evaluating local models. A model strong in English but mediocre in your target language will appear to have a retrieval problem when it is actually a generation problem.

​
Security & Privacy

No. Ragen is entirely self-hosted — there is no hosted offering, and no component reports back to the vendor. Your documents, your Postgres database, your Qdrant index, and your conversation history all live on infrastructure you control.The application contains no analytics, tag manager, or usage telemetry. An architecture test fails the build if any of those are added. Some of the services it runs alongside, such as Qdrant and Docling, have telemetry of their own. The local-model compose file switches it off; see What still reaches outward.
It depends on how you configure the model layer:Two caveats apply regardless:
  • Document parsing can fall back externally. DOCUMENT_PARSER=docling parses on your hardware, but if Docling fails the worker falls back to a loader that sends PDFs to an external model. Set DOCLING_STRICT=1 to fail ingest instead.
  • Content moderation goes directly outward. Moderation is a guardrail rule called content-moderation, switched on in the admin panel rather than by an environment variable. When it is on it calls OpenAI’s moderation endpoint directly — the one model call the route table cannot redirect. Leave the rule off on an isolated install.
See Security and Privacy for the full breakdown.
Encryption at rest is opt-in in development and mandatory outside it. Without a key provider configured, a development process starts and stores message content unencrypted, which keeps a fresh clone simple. Anywhere else — NODE_ENV other than development/test, and TARGET_ENV either unset or naming a real environment — a missing provider stops the process rather than writing plaintext, unless ALLOW_UNENCRYPTED=1 waives it as a logged, deliberate choice. See Encryption.Ragen supports AES-256-GCM encryption using envelope encryption: each conversation thread gets its own key, itself encrypted by a master key in your chosen key provider. Set ENCRYPTION_PROVIDER to one of:
  • scaleway — Scaleway Key Manager
  • kms — AWS KMS
  • local — a master key in the environment
After configuring a provider, send a test message and confirm that new conversation threads show as encrypted in the Ragen admin panel.
Thread titles remain in plaintext so title search works. Content search over encrypted threads is therefore title-only — this is a deliberate trade-off.
Yes, over OpenID Connect. Microsoft Entra ID, Google Workspace, Keycloak and any other issuer with a discovery document can sign people in. Sign-in is restricted to your own email domains, and new users can join your organization automatically. It is part of the open edition. See Company sign-in.SAML and SCIM provisioning are not built yet, and neither are MFA and passkeys. See the roadmap.

​
API & Integration

Yes. Ragen implements the OpenAI wire format for the endpoints most integrations rely on:
  • POST /v1/chat/completions — chat completions with streaming support
  • POST /v1/files, GET /v1/files, DELETE /v1/files/:id — file management
  • POST/GET/PATCH/DELETE /v1/assistants — assistant (project) management
  • POST/GET/PATCH/DELETE /v1/threads and messages — conversation thread management
You can point any OpenAI-compatible SDK at your Ragen instance by setting base_url to your deployment’s API address. Ragen adds one extension field, assistant_id, to specify which project to query.
Some OpenAI parameters are accepted but have no effect on the RAG pipeline yet (such as top_p and seed). A few are rejected with a 400 because silently dropping them would produce unexpected results — response_format and tools/tool_choice fall into this category.
Create an API key from within your Ragen instance:
1

Open Settings

Log in to your Ragen instance and navigate to Organization → API keys.
2

Create a key

Click Create API Key, give it a name, and select the project (assistant) this key should access.
3

Copy it immediately

The full key is only shown once at creation time. Copy it and store it securely — only a masked version is kept in the database.
Optionally enable Debug mode on the key to save every API conversation as a thread in the project view, which is useful when building and testing integrations.
Yes. Rate limits apply per IP address:Chat completions run the full RAG pipeline (vector search + optional reranking + LLM call), and file uploads trigger the ingest pipeline, so both carry the stricter limit. When a limit is hit, the response is 429 rate_limit_error. The official TypeScript SDK retries 429 responses automatically with exponential backoff and jitter.
Yes. Point the base_url at your Ragen instance and pass assistant_id as an extra body parameter:
example.py
The extra_body field passes Ragen’s assistant_id extension through the OpenAI SDK without triggering a validation error. Streaming works the same way — set stream=True and iterate the response as you normally would.
A native Python client for Ragen is on the roadmap. Once available, it will provide typed responses and helpers like wait_until_processed() that the OpenAI SDK cannot offer.