Skip to main content
Ragen AI is self-hosted, so getting started means getting an instance running on your own machine. One command — npx create-ragen-app — scaffolds the entire stack locally: Postgres, Qdrant, Redis, Docling and all five applications. Budget about ten minutes, most of it Docker pulling images.
Rather not install anything? Deploy on Railway runs the whole stack from a template with one OpenRouter key.

​
Prerequisites

Before you begin, make sure you have the following in place:
  • Node.js ^24.15.0 || >=26.0.0 — the installer checks your version before it clones anything. It is a range rather than a floor: 24.0–24.14 and all of 25 fail npm install on a transitive engine constraint, far from the actual cause.
  • Docker and Docker Compose — both must be running. The backing services (Postgres, Qdrant, Redis, Docling) all run in containers.
  • 8 GB of RAM available to Docker. The containers idle at about 900 MB together — document parsing is most of it — so the rest is headroom for parsing under load and for the apps. What the stack actually costs has the breakdown, including how to run a smaller stack.
  • An LLM API key — OpenAI or Anthropic to start chatting immediately. You can also point Ragen at models on your own hardware, but that is separate deployment work.
No GPU is required unless you choose to serve models locally.

​
Steps

1

Scaffold your installation

Run the following command in your terminal to scaffold a new Ragen instance:
If you would rather have a ragen command on your PATH, npm i -g ragen-cli provides one and ragen create my-ragen-app runs the same wizard with the same flags. See the CLI page.
The wizard clones the repository, generates every secret it safely can, starts the backing services in Docker, and runs the first-time setup — the Prisma client, schema migrations, and the seed data. It does not start the applications themselves; that is the next step.Five questions, in this order:
Several flags let you control what the installer does:
2

Start the apps

Move into your new directory and start each application in a separate terminal. There is no single root dev script because these are separate processes with separate lifetimes.
apps/api is not optional. The web app delegates thread creation, the thread sidebar, and notifications to it. Starting only the web app gives you a panel that loads but a chat that cannot open a thread.
apps/worker is what turns an uploaded file into searchable chunks. Without it, an upload returns 200 and the document sits in a pending state indefinitely — nothing in the web UI explains why. Start the worker in a third terminal before uploading any documents.
Once all three required processes are running, your local stack looks like this:
3

Create your first account

Open http://localhost:3000 in your browser. A fresh install redirects you to a first-run setup page where you choose the platform administrator’s name, your organization name, and a password. That account can then create all other accounts on the platform.
If anything required is still misconfigured, the setup page lists the missing environment variable by name and tells you what breaks without it — rather than showing a stack trace. An unreachable database is reported the same way.
4

Upload a document and ask a question

With your account created, you are ready to build your first knowledge base and query it.
1

Create a project

A project is a self-contained knowledge base with its own documents and its own assistant instructions. Create one from the main navigation.
2

Upload a document

Upload any supported file (PDF, DOCX, XLSX, CSV, Markdown, plain text, images, and more) to your project. Parsing happens asynchronously in the worker — watch the document’s status indicator to see when it becomes searchable.
3

Ask a question in chat

Open the chat for your project and ask a question. The answer is grounded in the document you uploaded, with citations linking back to the exact source passages.

​
Verify your installation

Once everything is running, confirm each service is healthy:
The last one is the check the other two cannot stand in for. Ragen calls model providers itself, so “the services are up” says nothing about whether a credential works — and a provider that is configured but unauthenticated fails at the first question a user asks, not at boot.
If document ingestion appears to hang, check the worker log first. The upload endpoint returns 200 as soon as the file is stored — parsing is asynchronous, and a parsing failure is only visible in the worker log and in the document’s status field in the UI.

​
Next steps

Self-Hosting

The manual deployment path, what each service does, and the settings that matter most in production — encryption, storage, and the embedding model.

API Quickstart

Make your first call against the instance you just built using the TypeScript SDK.

Concepts

Understand projects, organizations, RAG, and access control before you go further.

Configuration

Every environment variable, which app reads it, and what breaks when it is missing.