Skip to main content

Invoke OpenRAG with uvx

Use uvx to invoke OpenRAG outside of a Python project or without modifying your project's dependencies.

This installation method is best for testing OpenRAG by running it outside of a Python project. For other installation methods, see Select an installation method.

When you install OpenRAG with uvx, you will use the Terminal User Interface (TUI) to configure and manage your OpenRAG deployment.

info

uvx openrag installs the latest version of OpenRAG and dependencies, like Docker or Podman, if they aren't already present in your environment.

Prerequisites​

  • Install Python version 3.12 or later.
  • Install uv.

  • Gather the credentials and connection details for one or more supported model providers:

    • OpenAI: Create an OpenAI API key.
    • Anthropic: Create an Anthropic API key. Anthropic provides language models only; you must select an additional provider for embeddings.
    • IBM watsonx.ai: Get your watsonx.ai API endpoint, IBM project ID, and IBM API key from your watsonx deployment.
    • Ollama: Deploy an Ollama instance and models locally, in the cloud, or on a remote server. Then, get your Ollama server's base URL and the names of the models that you want to use.

    OpenRAG requires at least one language model and one embedding model. If a provider offers both types of models, then you can use the same provider for both models. If a provider offers only one type, then you must configure two providers.

    Language models must support tool calling to be compatible with OpenRAG.

    For more information, see Complete the application onboarding process.

  • Optional: Install GPU support with an NVIDIA GPU, CUDA support, and compatible NVIDIA drivers on the OpenRAG host machine. If you don't have GPU capabilities, OpenRAG provides an alternate CPU-only deployment that is suitable for most use cases. The default CPU-only deployment doesn't prevent you from using GPU acceleration in external services, such as Ollama servers.

Install and run OpenRAG with uvx​

  1. Create a directory for your OpenRAG configuration files and data, and then change to that directory:

    mkdir openrag-workspace
    cd openrag-workspace

  2. Optional: If you want to use a pre-populated OpenRAG .env file, create one at ~/.openrag/tui before invoking OpenRAG.

  3. Invoke OpenRAG and install any missing dependencies:

    uvx openrag

    You can invoke a specific version using any of the uvx version specifiers, such as uvx --from openrag==0.1.30 openrag.

  4. If needed, respond to any prompts to install and configure dependencies like Docker or Podman.

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

Invoking OpenRAG with uvx openrag creates a cached, ephemeral environment for the TUI in your local uv cache. Your OpenRAG configuration files and data are stored in ~/.openrag, which is separate from the uv cache. Clearing the uv cache doesn't remove your entire OpenRAG installation; it only clears uv dependencies. After clearing the cache, you can re-invoke OpenRAG (uvx openrag) to restart the TUI with your preserved configuration and data.

If you encounter errors during installation, see Troubleshoot OpenRAG.

Set up OpenRAG with the TUI​

When you install OpenRAG with uvx, you manage the OpenRAG services with the TUI. The TUI guides you through the initial configuration process before you start the OpenRAG services.

Your configuration values are stored in an OpenRAG .env file that is created automatically at ~/.openrag/tui. If OpenRAG detects an existing .env file in this directory, then the TUI can populate those values automatically during setup and onboarding.

Container definitions are stored in the docker-compose files in the same directory as the OpenRAG .env file.

  1. In the TUI, click either Basic Setup or Advanced Setup.

    info

    You must use Advanced Setup if you want to enable either OAuth mode or cloud storage connectors during initial set up:

    • OAuth mode: Controls document ownership and access in your OpenRAG OpenSearch knowledge base. Without OAuth mode, there is no differentiation between users; all users that access your OpenRAG instance can access and manage all uploaded documents.
    • Cloud storage connectors: Enables ingestion of documents from external storage services.

    If OpenRAG detects OAuth or cloud storage connector credentials during setup, it recommends Advanced Setup in the TUI.

    You can also enable these features later.

  2. Enter administrator passwords for the OpenRAG OpenSearch and Langflow services.

    The OpenSearch password is required, and a secure password is automatically generated if you don't provide one manually.

    The Langflow password is recommended but optional. If the Langflow password is empty, the Langflow server starts without authentication enabled. For more information, see Langflow settings.

    You can click Generate Password to create a Langflow password and username automatically.

  3. Optional: Under API Keys, enter your model provider credentials, or leave these fields empty if you want to configure model provider credentials during the application onboarding process.

    There is no material difference between providing these values now or during the application onboarding process. If you provide a credential now, it can be populated automatically during the application onboarding process if you enable the Use environment API key option.

    OpenRAG's core functionality requires access to language and embedding models. By default, OpenRAG uses OpenAI models. If you aren't sure which models or providers to use, you must provide an OpenAI API key to use OpenRAG's default model configuration.

  4. Advanced Setup only: To enable OAuth mode or cloud storage connectors, do the following:

    1. Register OpenRAG as an OAuth application in your cloud provider, and then obtain the app's OAuth credentials, such as a client ID and secret key. To enable multiple connectors, you must register an app and generate credentials for each provider.

    2. Enter the relevant OAuth credentials under API Keys in the TUI's Advanced Setup:

      The credentials can be populated automatically if OpenRAG detects these credentials in an OpenRAG .env file at ~/.openrag/tui.

    3. Register the redirect URIs shown in the TUI in your OAuth apps.

      The redirect URIs are used for the cloud storage connector webhooks. For Google, the redirect URIs are also used to redirect users back to OpenRAG after they sign in.

  5. Optional: Under Langfuse (Tracing), enter Langfuse credentials to enable the Langflow integration with Langfuse:

    • Langfuse Secret Key: A secret key for your Langfuse project.
    • Langfuse Public Key: A public key for your Langfuse project.
    • Langfuse Host: Required for self-hosted Langfuse deployments. Leave empty for Langfuse Cloud.

  6. Optional: Under Others, you can edit the following settings if needed:

    • Documents Paths: Set the local documents path. Use the default path, or provide a path to a directory where you want OpenRAG to look for documents to ingest into your knowledge base.
    • OpenSearch Data Path: Use the default path, or specify the path where you want OpenRAG to create your OpenSearch index.
    • Langflow Public URL (Advanced Setup only) : Sets the base address to access the Langflow web interface where users interact with the Langflow editor in a browser. You must set this value to run Langflow on a non-default port (7860)
    • Webhook Base URL (Advanced Setup only): If you entered OAuth credentials, you can set the base address for your OAuth connector endpoints. If set, the OAuth connector webhook URLs are constructed as WEBHOOK_BASE_URL/connectors/${provider}/webhook. This option is required to enable automatic ingestion from cloud storage.

  7. Click Save Configuration.

    Your passwords, API key, and OAuth credentials (if provided) are stored in the OpenRAG .env file at ~/.openrag/tui. If you modified any credentials that were pulled from an existing .env file, those values are updated in the .env file.

  8. Click Start OpenRAG to start the OpenRAG 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:

    Services started successfully
    Command completed successfully

  9. Click Close, and then click Launch OpenRAG or navigate to localhost:3000 in your browser.

    If you provided Google OAuth credentials, you must sign in with Google before you are redirected to your OpenRAG instance.

  10. Continue with the application onboarding process.

Complete the application onboarding process​

The first time you start the OpenRAG application, you must complete the application onboarding process to select language and embedding models that are essential for OpenRAG features like the Chat.

To complete onboarding, you must configure at least one language model and one embedding model.

You can use different providers for your language model and embedding model, such as Anthropic for the language model and OpenAI for the embedding model. Additionally, you can select multiple embedding models.

info

Anthropic doesn't provide embedding models. If you select Anthropic for your language model, you must select a different provider for the embedding model.

  1. Enter your Anthropic API key, or enable Use environment API key to pull the key from your OpenRAG .env file.

  2. Under Advanced settings, select the language model that you want to use.

    Language models must support tool calling to be compatible with OpenRAG. Incompatible models aren't listed.

  3. Click Complete.

  4. Select a provider for embeddings, provide the required information, and then select the embedding model you want to use. For information about another provider's credentials and settings, see the instructions for that provider.

  5. Click Complete.

    After you configure the embedding model, OpenRAG uses your credentials and models to ingest some initial documents. This tests the connection, and it allows you to ask OpenRAG about itself in the Chat. If there is a problem with the model configuration, an error occurs and you are redirected back to the application onboarding screen. Verify that the credential is valid and has access to the selected model, and then click Complete to retry ingestion.

  6. Continue through the overview slides for a brief introduction to OpenRAG, or click Skip overview. The overview demonstrates some basic functionality that is covered in the quickstart and in other parts of the OpenRAG documentation.

Next steps​