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, the model gateway, and all four applications. Budget about ten minutes, most of it Docker pulling images.

​
Prerequisites

Before you begin, make sure you have the following in place:
  • Node.js 24.x — the installer checks your version before it clones anything. Running on an older version produces a tree that fails later, far from the actual cause.
  • Docker and Docker Compose — both must be running. The backing services (Postgres, Qdrant, Temporal, Docling, Redis) all run in containers.
  • ~8 GB of RAM available to Docker. Document parsing is the hungry part; you can drop Docling later if you need to trim memory.
  • 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:
The wizard clones the repository, generates every secret it safely can, prompts you for a model provider key, asks how you want storage and encryption configured, 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.
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.