Ragen AI - now open-sourced 🎉

Turn your company documents into an AI assistant that answers from your data — on your own servers, with your own models.

Live demo · Documentation · Quickstart · API reference · TypeScript SDK · Security review · Self-hosting · Open models

npx create-ragen-app my-ragen-app
cd my-ragen-app
npm run api:dev      # one terminal each: chat needs the API,
npm run web:dev      # and an upload is only parsed
npm run worker:dev   # while the worker runs

Needs Node.js ^24.15.0 || >=26.0.0 and Docker; Quick start has the details.

Or try it without installing anything — one click, one OpenRouter key:

Built and maintained by Web Amigos.

🧩 The problem

Most "chat with your documents" tools land in one of two places. Either they are a demo — naive top-k cosine search over a pile of PDFs, confidently wrong the moment a question needs more than one document — or they are a SaaS product you hand your contracts, personnel files and client data to, on someone else's infrastructure, under someone else's retention policy.

Ragen is neither. It is an open-source RAG platform for companies that you run yourself: retrieval that has been measured rather than assumed, access control enforced where it actually matters, and a model layer you can point at your own hardware.

Related MCP server: Agentic RAG MCP Server

💡 Why Ragen

Permissions are enforced at retrieval, not in the UI. A document a user cannot open cannot appear in an answer, or in a citation, or in the context sent to the model. Every chunk carries an accessible_by filter applied at query time. Most tools filter the file list and pass everything to the prompt.

Retrieval that was measured, not assumed. Hybrid dense + BM25 sparse search with server-side RRF, multi-query expansion, document summaries generated at ingest, and cross-encoder reranking over the result set. Four composed techniques — the first three on by default, reranking once you give it a provider — each with an ADR recording what it changed and what it cost: ADR-14, ADR-15, ADR-16, ADR-12. Retrieval quality, rephrasing and red-team behaviour all have eval datasets you can run yourself: apps/web/evals.

Your infrastructure, your keys. Documents, database, vector index and encryption keys stay where you put them. No component reports back to us, and there is no hosted tier we would rather sell you. docs/security-and-privacy.md sets out exactly what leaves your network under which configuration — including the two cases where the honest answer is "it depends how you set it up".

No lock-in on the model. Ragen calls providers itself, or goes through a gateway you run — LiteLLM, Portkey, vLLM, Ollama, anything speaking OpenAI's API. Scaleway, Azure OpenAI, AWS Bedrock, Google Vertex, OpenRouter, or a model on your own GPU — changing provider is a route, not a migration.

Multi-tenancy is structural. One Qdrant collection per organization, a tenant-scope guard in the Prisma layer that flags any query missing its org filter, and two deliberately separate role hierarchies. It was designed in, not retrofitted.

Drop-in API. An OpenAI-compatible REST API and an official TypeScript SDK (@webamigos/ragen-sdk-ts) with streaming, typed responses and upload helpers. Most existing clients work by changing the base URL.

🛠️ Crafted by hand. Extended by agents.

Ragen was not generated. Two years and 3,200 commits of hand-written architecture came first — the tenant-scope guard, the retrieval permission model, the CQRS feature modules, the shared contracts package. 52 ADRs record what was rejected and why.

Only then did the agent harness go on top: AGENTS.md as the canonical brief, five repo-specific skills for the operations that actually go wrong here (tenant-scope audits, RAG changes with measurement, e2e triage, dependency upgrades), and architecture tests that fail the build when a rule is broken rather than trusting a comment to hold it.

That order is the point. An agent working in this repository is not inventing conventions — it is following ones that survived production. The entries in docs/lessons/ are the incidents that taught us which guardrails had to be executable.

What that buys you: your team's AI coding agent is useful here on day one, because the invariants it has to respect are written down, linked, and enforced by CI instead of living in someone's head.

🏗️ What people build with it

• Internal knowledge base — onboarding, procedures, contracts and project history, answerable in chat, with each answer citing the document it came from

• Customer-facing chatbot — an embeddable widget grounded in your public documentation, with a separate assistant configuration and its own limits

• RAG behind your own product — the OpenAI-compatible API and SDK as the retrieval layer of an application you are already building

• Regulated document sets — where the answer to "who could have read this?" has to be provable, and the documents cannot leave your infrastructure

• An assistant wired into your tools — Google Workspace, Slack, HubSpot, ClickUp and more over MCP, so the model can read live systems mid-conversation rather than only what was indexed last night

• A curated knowledge layer — Ragen Brain turns a shared drive into knowledge pages with owners, finds where the documents contradict each other or have gone stale, and lets only what a person approved reach the assistant

📸 Screenshots

The app itself — an assistant answering from a knowledge base:

The knowledge base, where documents are uploaded, versioned and shared:

Settings, which is where most of the per-user and per-organization behaviour is decided:

Ragen Brain turns the documents into knowledge pages people review and own. The overview shows where each document stands on the way to a chat answer — extracted, to review, approved, published — and what needs attention next:

Every knowledge page is listed with its status, owner and open problems; only approved pages can be published to the knowledge base:

A knowledge page: the claims, each with the quoted passage it came from, its owner, who may read it, its relations to other pages, and whether it is in the knowledge base yet:

Problems are what needs a person's attention — contradictions between pages, gaps, stale pages, pages with no owner and documents Brain could not read:

The graph shows how pages connect, so a curator sees what the corpus actually says, what depends on what, and where the gaps are:

Sources lists the documents Brain reads, how many pages each one yielded and how many of them are approved:

The platform admin panel — one installation, every organization in it. This is the operator's surface and a separate app; the per-organization settings a customer's own owners and admins use live in the main app, and neither is a bigger version of the other. The two roles are unrelated fields on unrelated tables: Two kinds of administrator.

Connector health, showing which MCP integrations are failing and why:

Every page of the panel is documented, with screenshots regenerated from a scripted demo state rather than captured by hand: Admin panel.

Or skip the screenshots and use it: the app is live at demo.ragen.ai, running against a seeded showcase organization rather than real customer data. The admin panel is the operator's surface and has no public instance — the page above is what it looks like.

⚖️ How it compares

Fair warning on the middle column: if your requirements are genuinely unusual, building it yourself is a legitimate answer. Ragen is the better trade when you want those decisions already made — and documented — rather than made by you.

🚀 Quick start

One click on Railway

The template deploys the whole stack — web app, API, ingest worker, Docling, Ragen Brain (switched on), the MCP server, the admin panel and the token vault, with Postgres, Redis, Qdrant and an S3 bucket — and asks for one value, an OpenRouter key. Every secret is generated for you. Claude Sonnet 5.5 answers, Claude Haiku 5.5 rephrases and summarises, text-embedding-3-small embeds. The first account you create becomes the platform administrator. PII masking (Presidio) and content moderation are not part of it, and mail is not configured until you add RESEND_API_KEY or SMTP_*. Back up ENCRYPTION_MASTER_KEY on the web service: thread messages are encrypted under it and nothing can recover it. What is in the template and why: docs/railway-template.md.

On your own machine

Don't have the repo yet:

npx create-ragen-app my-ragen-app

create-ragen-app clones the repo, generates every secret it safely can, lets you paste a plain OpenAI or Anthropic key instead of configuring an enterprise LLM provider, starts the backing services in Docker, and runs the first-time Prisma setup — ending at three processes to start, each in its own terminal: npm run api:dev, npm run web:dev and npm run worker:dev. The web app alone loads, but cannot open a chat without the API or parse an upload without the worker. Requires Node.js ^24.15.0 || >=26.0.0 — a range rather than a minimum, and the wizard refuses outside it before it clones anything; --skip-docker, --skip-install and --yes are available for a more manual or scripted run.

Rather run the applications in containers too:

npx create-ragen-app my-ragen-app --skip-install
cd my-ragen-app && npm run ragen:up:everything

With --skip-install the wizard only writes .env.local — the secrets, your model key and the model names — and installs nothing. The stack then pulls the release images of every Ragen application (web, API, ingest worker, admin), migrates and seeds the database itself, and starts them alongside Postgres, Qdrant, Redis and Docling. Already have the repo cloned and a .env.local? npm run ragen:up:everything on its own does the same.

Each image carries four tags — the full version, the minor series, the exact commit (sha-…) and latest, which is what the stack pulls unless RAGEN_VERSION in .env names another. Pin production to the sha- tag; the other three move. To run the code in your checkout instead of a release — a branch, an unreleased fix — npm run ragen:up:everything:source builds the images first, one at a time, which takes the better part of an hour the first time.

Either way, open http://localhost:3000. A new install asks you to create its first account, which becomes the platform administrator; then upload a document under Knowledge and ask it something.

Requirements

No GPU, unless you want one. Chat, embeddings and reranking all leave over the network, so the machine running Ragen does no model inference of its own. Point it at a hosted provider and a laptop is enough. A GPU only enters the picture if you decide to serve models yourself, which is supported and is a separate box.

Where the memory actually goes. Measured on an idle stack, backing services only:

Three of those are optional, and together they are most of the total — the table is the stack with every optional part switched on. Presidio is not in a default docker compose up at all: both of its services sit behind the pii profile, so unless you asked the installer for PII masking the idle stack is about 900 MB rather than 1.9 GB. Drop Presidio if you are not masking PII, DOCUMENT_PARSER=legacy skips Docling, and Ragen calls model providers itself, so there is no proxy in this table any more — the litellm services went with the path that used them. Qdrant is the line that moves as you add documents; the figure above is a near-empty index, so size that one against your own corpus rather than against this table. Redis is not optional under the default runtime — it holds the ingest queue, and rate limiting rides along on it. The four applications run on top of all this and are not in the table.

npm run ragen:up:app is not a smaller way to run Ragen any more: it brings up Postgres and Qdrant without Redis, which was a working chat-only stack while Redis was merely a cache. Under BullMQ (ADR-44) it is not — apps/web and apps/api validate REDIS_URL at boot whether or not you ever upload a document, because a producer that cannot reach the queue cannot enqueue at all. Use ragen:up:full. Sizing guidance for larger installs is in Self-hosting.

For development, npm run ragen:up:full runs the dependencies in containers and leaves the apps running from source with hot reload. To contribute without installing any of it, the repository ships a dev container — Code → Codespaces on GitHub, described in .devcontainer/README.md. Full instructions: Self-hosting · Local development.

✨ Features

Retrieval Hybrid dense + BM25 sparse search over Qdrant · multi-query expansion · ingest-time document summaries · cross-encoder reranking (opt-in, needs a provider) · citations on every answer · per-organization vector collections

Knowledge base Nested folders · per-user file ownership · sharing with users and teams · document versions with diff and rollback · re-indexing on content change · RAG optimization suggestions you review before accepting

Documents PDF, DOCX, XLSX, CSV, EPUB, SRT, Markdown, plain text, images and URLs · local parsing with Docling by default · async ingest on a queue, so a large upload does not block anything

Integrations (MCP) Client and server both · Google Workspace, Gmail, Slack, HubSpot, ClickUp, Fireflies, WooCommerce · four auth styles including OAuth with PKCE · OAuth tokens held in a separate vault service, never in the application database · a Ragen assistant is also itself callable as an MCP tool (apps/mcp) by external clients like Claude Desktop or Cursor — with the same API key as the REST API, or by signing in as a Ragen user over OAuth (ADR-53) · the connector catalogue is data a platform admin edits, not a hard-coded list

Ragen Brain (preview, off by default) Knowledge pages extracted from your documents, each claim citing its source passage · review inbox: approve, reject, merge, set owner and access · findings for contradictions, gaps, stale and unowned knowledge · knowledge graph · publishing to the index only by a person, and withdrawable · an operator's assistant that proposes changes but never applies them · bundle export (markdown + graph.json) · read-only ragen brain CLI

API and SDK OpenAI-compatible REST API · official TypeScript SDK · opaque API keys · streaming over SSE · embeddable chatbot widget · ragen CLI for the knowledge base, search and Brain

Security Opt-in AES-256-GCM envelope encryption, one key per conversation · optional PII masking via Presidio · per-organization guardrail rules on input and output · audit log with before-and-after state · tenant-scope guard over ~20 models · no training on your documents, ever

Operations Platform admin app · per-organization model allowlists and usage limits · OpenTelemetry traces, metrics and logs · UI in 17 languages — English, Polish, Spanish, German, French, Portuguese, Italian, Hungarian, Bulgarian, Ukrainian, Danish, Swedish, Finnish, Czech, Slovak, Dutch and Norwegian

⚙️ How it works

Ingest — a file lands in storage, and a background job takes over: parse, chunk with a splitter chosen for the file type, generate a summary of the whole document, prepend that summary as its own chunk, embed densely and sparsely, upsert into the organization's Qdrant collection. It runs asynchronously, so a 400-page PDF does not block anything.

upload → parse → chunk → summarize → hybrid embed → Qdrant

Retrieval — a question is first rewritten into a standalone one using the conversation so far, then expanded into an alternative phrasing. Both run as hybrid searches in parallel; Qdrant fuses dense and sparse results server-side with RRF; the union is deduplicated and, when a rerank provider is configured, passed to a cross-encoder before the model sees it, with citation prompting on top.

question → standalone → +1 variant → 2× hybrid search → RRF → dedupe → rerank → answer

Hybrid search is not a toggle — it is the schema collections are created with, so it is always on. Reranking is: it needs FEATURE_FLAG_RERANKING=1 and a provider's credentials, and is skipped without them. Every stage degrades rather than fails — a reranker error falls back to the raw vector order, an expansion error falls back to a single query. Tuning constants and flag names: docs/rag-pipeline.md.

🧠 Ragen Brain

Retrieval over raw documents has a blind spot: nothing in it decides what is true. When two documents disagree, the answer depends on whichever chunk ranks higher; nothing says who vouches for a statement or when it was last checked; and a file is live in chat the moment its ingest finishes.

Ragen Brain is the curation layer that closes it. A background job reads the organization's documents and proposes knowledge pages — processes, policies, products, roles, entities — where every claim cites the exact passage it came from. Alongside them it produces findings: contradictions between documents, gaps, stale pages, pages with no owner, and documents extraction could not read. A curator works through them in a review inbox — approve, reject, merge, assign an owner, set who may read the page — and every decision lands in a ledger naming the person who made it. The graph view shows how pages relate and where the corpus is thin.

What makes it safe to switch on is that nothing reaches retrieval on its own:

• A page enters the index only when a person publishes it, and unpublishing removes its chunks again. Brain never publishes a source document.

• A page built from several documents is readable by the intersection of their audiences. Widening that is an explicit, logged decision.

• Uploads can be staged in Brain alone — parsed and curated, never indexed — so a shared drive can be explored without changing what the assistant says.

• The operator's assistant beside Brain only proposes. Every change it suggests is applied by a person, through the same action a button runs.

An answer that cites a published page says so, and names only the source documents the caller may open. The curated knowledge can be exported as a bundle (markdown, graph.json, a manifest) or read from a terminal with ragen brain (packages/ragen-cli).

Brain ships as packages/brain-core and packages/brain-contracts, with its screens in apps/web and its jobs in apps/worker — no extra service to deploy. It is still being built across releases, so it sits behind the brain feature key, off by default, per organization. Design and decisions: the Ragen Brain spec and the operator's assistant.

🔒 Security and privacy

Ragen is self-hosted. Documents, database, index and encryption keys stay on infrastructure you control, and nothing reports back to the vendor. Whether document content leaves your network during processing depends on how you configure the model backend — which is a real decision, not a detail, and the document below treats it as one.

docs/security-and-privacy.md answers the questions that come up in a security review: where data lives, what leaves the network, encryption, access control, audit logging, and whether documents are used for training. Every claim points at the code or the ADR behind it, and says plainly where something is configuration-dependent or not yet built.

Open models on your own hardware is the other half of that answer: how to point Ragen at a vLLM or Ollama server you run — directly or through a proxy — the four model settings that keep a cloud default until you change them, and the calls that still reach outward once you have.

Two things worth knowing before you deploy:

• Parsing is local by default, but it falls back. DOCUMENT_PARSER=docling parses on your own hardware; if Docling fails, the worker falls back to loaders that send PDFs to an external model. Set DOCLING_STRICT=1 to fail instead of falling back.

• Encryption at rest is opt-in. With no key provider configured, Ragen starts normally and stores message content unencrypted — convenient locally, wrong in production. Set ENCRYPTION_PROVIDER.

We would rather tell you this here than have you find it during an audit.

🔓 Open core

Ragen is licensed under Apache 2.0. The rule for what that covers is deliberately mechanical: if a directory contains its own LICENSE file, that file governs everything under it. Everything else is Apache 2.0. No per-file headers, no allowlists, no exceptions you have to go looking for. Commercial paths today: none — the entire repository is Apache 2.0.

Three commitments constrain what may ever change:

• Security is not an upsell. Tenant isolation, encryption at rest, PII masking and access control are core and stay core. Charging extra for the mechanisms that give you control over your own data would undercut the point of the product.

• The core never degrades because the commercial layer is absent. Ragen runs without Stripe, without Presidio, without a telemetry backend and without AWS KMS. An install with no commercial licence is a complete Ragen, not a crippled one.

• Multi-tenancy is core. Organization scoping runs through the data model, the vector store and the access-control layer. It could not be withheld without dismantling the architecture, and it will not become a paid tier.

Full text, including how this affects contributions: docs/open-core-boundary.md.

🗺️ Roadmap

No dates. The order below is what we are working on, and it changes when a real install needs something we did not expect. Open work lives in GitHub Issues; this section is the shape of it rather than a substitute for it.

Next

• Pluggable infrastructure, and a smaller install as the payoff. Three parts of the stack are things you should be able to choose rather than inherit: the job runtime, the vector store and the document parser. Each has a spec that puts a seam in front of it — BullMQ as the worker runtime, pgvector alongside Qdrant, Mistral Document AI alongside Docling. Two of the three only add a choice: Qdrant stays the default vector store and Docling stays the default parser. The worker is the exception, and it has landed — BullMQ is the runtime (ADR-44), Temporal is an adapter behind the same seam, and what is still ahead is moving that adapter to a separate repository, where it stays supported for installs that want durable execution. A fourth spec, the in-process model gateway, replaced the LiteLLM proxy.

  The payoff is that an install can be assembled to fit: select every alternative and Ragen runs on a small VM, or on managed Postgres with no container orchestration at all — without that becoming the only shape on offer. The trade-offs are real and each spec states them: a hosted parser means your documents leave your deployment, pgvector shares a failure domain with your database, and BullMQ re-runs a crashed job instead of resuming it.

• A Python client. The TypeScript SDK is official and published. Python is the language most people integrating the API are actually writing in.

• Slack as a place to ask. Not the existing Slack connector, which reads Slack as a source, but an assistant you can talk to in a channel, carrying the same retrieval-time access filter as the application.

• A verified air-gapped configuration. A local model, local embeddings, DOCLING_STRICT=1, and a script that demonstrates no outbound traffic. The pieces are all there today.

• Microsoft Entra ID sign-in. SSO and MFA are not built yet. Entra ID over OAuth comes first; SAML and SCIM directory sync come after it.

• docker compose up to a working demo, with sample documents and sample questions, so evaluating Ragen does not begin with an empty knowledge base.

• Microsoft 365 connectors: SharePoint, OneDrive, Outlook, Teams.

• Feedback collection in the application, which is the signal the retrieval work has been missing.

Later

• Permissions inherited from the source system. Today accessible_by is set in Ragen. Reading permissions out of Google Drive and SharePoint and keeping them in sync is the harder and more useful version, including revocation taking effect without waiting for a reindex.

• Confluence and Jira connectors

• Web search and multi-step research as tools, opt-in per organization, because some installs deliberately have no outbound path and that has to stay true

• Audit log and security-event export to a SIEM, with retention and automatic deletion

• Organization export, so leaving Ragen is a documented procedure rather than a support conversation

• Fail-closed encryption: refuse to start in production without a key provider, instead of starting and storing message content unencrypted

• MFA and passkeys

• Per-user permissions for individual MCP tools

• Usage drill-down from organization to team to user to request, with budget alerts

• A sizing guide, a versioning policy and a CHANGELOG

Not planned

Worth saying plainly, because it saves you evaluating us for something we are not building:

• Image generation, advanced voice mode, a code interpreter. Ragen answers from your documents. A general-purpose assistant is a different product and there are good ones.

• A knowledge graph in the retrieval path. We would rather improve retrieval we can measure than add a stage we cannot. Ragen Brain's graph is a curation view for people; what reaches an answer is still a published page, retrieved like any other document.

• A visual workflow builder. Tools reach Ragen over MCP. The work we would rather do in that layer is approval and audit, not a node canvas.

Influencing this. Open an issue describing the install you are trying to do. A deployment blocked on a missing connector moves faster than a feature request in the abstract.

🏛️ Architecture at a glance

An npm-workspaces monorepo on Turborepo. 5 applications and 17 packages share one Prisma schema.

How the pieces fit at runtime:

flowchart LR
    user([Browser]) --> web["apps/web<br/>Next.js app"]
    client([API clients]) --> api["apps/api<br/>NestJS, OpenAI-compatible"]
    agent([MCP clients<br/>Claude Desktop, Cursor]) --> mcp["apps/mcp<br/>MCP server"]
    operator([Platform operator]) --> admin["apps/admin<br/>platform admin"]

    mcp --> api
    web <--> api
    web -- "enqueue jobs" --> redis[("Redis<br/>BullMQ queue")]
    api -- "enqueue jobs" --> redis
    redis --> worker["apps/worker<br/>ingest, embedding,<br/>re-indexing, Brain"]

    web --> pg[("Postgres<br/>one Prisma schema")]
    api --> pg
    admin --> pg
    worker --> pg
    web --> qdrant[("Qdrant<br/>hybrid dense + sparse")]
    api --> qdrant
    worker --> qdrant

    worker --> docling["Docling<br/>document parsing"]
    worker -. "optional" .-> presidio["Presidio<br/>PII masking"]
    web --> models["Model providers<br/>your keys or your own GPU"]
    api --> models
    worker --> models

Supporting services — Docling, Presidio, the OTel collector — live in infra/, each with its own deployment config.

The full picture — routing, auth, the settings and admin surfaces, the feature modules, the connector registry — is in docs/architecture.md. What each companion service is and how to run the set locally: docs/companion-services.md.

52 ADRs record the decisions and what was rejected. Start with ADR-21 for the monorepo shape and ADR-33 for why shared values live in one package.

📚 Documentation

Deeper reference, in docs/: architecture · RAG pipeline · knowledge base · document versioning · document processing · Ragen Brain · vector store · MCP integrations · token vault · file storage · companion services · model routing · event bus · thread encryption · tenant-scope guard · testing conventions · lessons

🛟 Need help?

Deploying Ragen in your company, getting retrieval right on your own documents, or an SLA and rollout support from the people who build it? Get in touch. For bugs and questions from the community, use Issues and Discussions.

🤝 Contributing

Pull requests are welcome on everything under Apache 2.0. Start with CONTRIBUTING.md, and read AGENTS.md before your first change — it is the canonical brief for both humans and coding agents, and it will save you a review round. Everyone taking part follows the Code of Conduct. Security issues go through SECURITY.md, not the public tracker.

Questions, ideas and "has anyone deployed this against X" belong in Discussions. Issues are for work with a definition of done; a discussion does not need one.

📄 License

Apache 2.0. See Open core for the boundary rule.

ℹ️ About

Ragen is built and maintained by Web Amigos, an IT company in Poland. We build it because our own clients needed it and would not put their documents in someone else's cloud.

Commercial support, deployment help and enterprise terms: ragen@webamigos.pl.