---
title: Quickstart
slug: /quickstart
---

import Icon from "@site/src/components/icon/icon";
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import PartialIntegrateChat from '@site/docs/_partial-integrate-chat.mdx';
import PartialPrereqWindows from '@site/docs/_partial-prereq-windows.mdx';
import PartialPrereqPython from '@site/docs/_partial-prereq-python.mdx';

Use this quickstart to install OpenRAG, and then try some of OpenRAG's core features.

## Prerequisites

<PartialPrereqWindows />

* Get an [OpenAI API key](https://platform.openai.com/api-keys).
This quickstart uses OpenAI for simplicity.
For other providers, see the other [installation methods](/install-options).

<PartialPrereqPython />

## Install OpenRAG

For this quickstart, install OpenRAG with the automatic installer script and basic setup.
The script installs OpenRAG dependencies, including Docker or Podman, and then it installs and runs OpenRAG with [`uvx`](https://docs.astral.sh/uv/guides/tools/#running-tools).

1. Create a directory for your OpenRAG installation, and then change to that directory:

   ```bash
   mkdir openrag-workspace
   cd openrag-workspace
   ```

2. [Download the OpenRAG install script](https://docs.openr.ag/files/run_openrag_with_prereqs.sh), move it to your OpenRAG directory, and then run it:

   ```bash
   bash run_openrag_with_prereqs.sh
   ```

   Wait while the installer script prepares your environment and installs OpenRAG.
   You might be prompted to install certain dependencies if they aren't already present in your environment.

   The entire process can take a few minutes.
   Once the environment is ready, the OpenRAG [Terminal User Interface (TUI)](/tui) starts.

   ![OpenRAG TUI Interface](@site/static/img/OpenRAG_TUI_2025-09-10T13_04_11_757637.svg)

3. In the TUI, click **Basic Setup**.

4. Click **Generate Passwords** to create administrator passwords for your OpenRAG OpenSearch and Langflow services.

5. Leave the **OpenAI API key** field empty.

   Your passwords are saved in the `.env` file that is used to start OpenRAG.
   You can find this file in your OpenRAG installation directory.

6. Click **Save Configuration**, and then click **Start All Services**.

   This process can take some time while OpenRAG pulls and runs the container images.
   If all services start successfully, the TUI prints a confirmation message:

   ```text
   Services started successfully
   Command completed successfully
   ```

   Your [OpenRAG configuration](/reference/configuration) is stored in a `.env` file that is created automatically in the directory where you ran the installer script.
   Container definitions are stored in the `docker-compose` files in the same directory.

7. Under [**Native Services**](/manage-services), click **Start** to start the Docling service.

8. From the TUI main menu, click **Open App** to launch the OpenRAG application and start the application onboarding process.

9. For this quickstart, select the **OpenAI** model provider, enter your OpenAI API key, and then click **Complete**. Use the default settings for all other model options.

10. Click through the overview slides for a brief introduction to OpenRAG, or click <Icon name="ArrowRight" aria-hidden="true"/> **Skip overview**.
You can complete this quickstart without going through the overview.
The overview demonstrates some basic functionality that is covered in the next section and in other parts of the OpenRAG documentation.

## Load and chat with documents {#chat-with-documents}

Use the [OpenRAG **Chat**](/chat) to explore the documents in your OpenRAG database using natural language queries.
Some documents are included by default to get you started, and you can load your own documents.

1. In OpenRAG, click <Icon name="MessageSquare" aria-hidden="true"/> **Chat**.

2. For this quickstart, ask the agent what documents are available.
For example: `What documents are available to you?`

   The agent responds with a summary of OpenRAG's default documents.

3. To verify the agent's response, click <Icon name="Library" aria-hidden="true"/> **Knowledge** to view the documents stored in the OpenRAG OpenSearch vector database.
You can click a document to view the chunks of the document as they are stored in the database.

4. Click **Add Knowledge** to add your own documents to your OpenRAG knowledge base.

   For this quickstart, use either the <Icon name="File" aria-hidden="true"/> **File** or <Icon name="Folder" aria-hidden="true"/> **Folder** upload options to load documents from your local machine.
   **Folder** uploads an entire directory.
   The default directory is the `/openrag-documents` subdirectory in your OpenRAG installation directory.

   For information about the cloud storage provider options, see [Ingest files with OAuth connectors](/ingestion#oauth-ingestion).

5. Return to the **Chat** window, and then ask a question related to the documents that you just uploaded.

   If the agent's response doesn't seem to reference your documents correctly, try the following:

   * Click <Icon name="Gear" aria-hidden="true"/> **Function Call: search_documents (tool_call)** to view the log of tool calls made by the agent. This is helpful for troubleshooting because it shows you how the agent used particular tools.

   * Click <Icon name="Library" aria-hidden="true"/> **Knowledge** to confirm that the documents are present in the OpenRAG OpenSearch vector database, and then click each document to see how the document was chunked.
   If a document was chunked improperly, you might need to tweak the ingestion or modify and reupload the document.

   * Click <Icon name="Settings2" aria-hidden="true"/> **Settings** to modify the knowledge ingestion settings.

   For more information, see [Configure knowledge](/knowledge) and [Ingest knowledge](/ingestion).

## Change the language model and chat settings {#change-components}

1. To change the knowledge ingestion settings, agent behavior, or language model, click <Icon name="Settings2" aria-hidden="true"/> **Settings**.

   The **Settings** page provides quick access to commonly used parameters like the **Language model** and **Agent Instructions**.

2. For greater insight into the underlying [Langflow flow](/agents) that drives the OpenRAG chat, click **Edit in Langflow** and then click **Proceed** to launch the Langflow visual editor in a new browser window.

   If Langflow requests login information, enter the `LANGFLOW_SUPERUSER` and `LANGFLOW_SUPERUSER_PASSWORD` from the `.env` file in your OpenRAG installation directory.

   The **OpenRAG OpenSearch Agent** flow opens in a new browser window.

   ![OpenRAG OpenSearch Agent flow](/img/opensearch-agent-flow.png)

3. For this quickstart, try changing the model.
Click the **Language Model** component, and then change the **Model Name** to a different OpenAI model.

   After you edit a built-in flow, you can click **Restore flow** on the **Settings** page to revert the flow to its original state when you first installed OpenRAG.

4. Press <kbd>Command</kbd>+<kbd>S</kbd> (<kbd>Ctrl</kbd>+<kbd>S</kbd>) to save your changes.

   You can close the Langflow browser window, or leave it open if you want to continue experimenting with the flow editor.

5. Switch to your OpenRAG browser window, and then click <Icon name="Plus" aria-hidden="true"/> in the **Conversations** tab to start a new conversation.
This ensures that the chat doesn't persist any context from the previous conversation with the original model.

6. Ask the same question you asked in [Load and chat with documents](#chat-with-documents) to see how the response differs from the original model.

## Integrate OpenRAG into an application

Langflow in OpenRAG includes pre-built flows that you can integrate into your applications using the [Langflow API](https://docs.langflow.org/api-reference-api-examples).
You can use these flows as-is or modify them to better suit your needs, as demonstrated in [Change the language model and chat settings](#change-components).

You can send and receive requests with the Langflow API using Python, TypeScript, or curl.

<PartialIntegrateChat />

## Next steps

* **Reinstall OpenRAG with your preferred settings**: This quickstart used `uvx` and a minimal setup to demonstrate OpenRAG's core functionality.
It is recommended that you [reinstall OpenRAG](/reinstall) with your preferred configuration and [installation method](/install-options).

* **Learn more about OpenRAG**: Explore OpenRAG and the OpenRAG documentation to learn more about its features and functionality.

* **Learn more about Langflow**: For a deep dive on the Langflow API and visual editor, see the [Langflow documentation](https://docs.langflow.org/).