Quick Start

Get Hrida.ai running on your machine. Pick your preferred method below.

macOSLinux x86_64ARM64 / Raspberry PiNVIDIA DGX SparkWindows

Docker: Officially supported and recommended for most users. Requires Docker installed.

Python: Suitable for low-resource environments or manual setups

Kubernetes: Ideal for enterprise deployments requiring scaling and orchestration

Docker
Python
Kubernetes
Desktop
Third Party

Quick Start with Docker

info

WebSocket support is required. Ensure your network configuration allows WebSocket connections.

1. Pull the image

docker pull ghcr.io/hrida-ai/hrida-ai-studio:main

2. Run the container

docker run -d -p 3000:8080 -v hrida-ai:/app/backend/data --name hrida-ai ghcr.io/hrida-ai/hrida-ai-studio:main

Flag	Purpose
`-v hrida-ai:/app/backend/data`	Persistent storage. Prevents data loss between restarts.
`-p 3000:8080`	Exposes the UI on port 3000 of your machine.

3. Open the UI

Visit http://localhost:3000.

Image Variants

Tag	Use case
`:main`	Standard image (recommended)
`:main-slim`	Smaller image, downloads Whisper and embedding models on first use
`:cuda`	Nvidia GPU support (add `--gpus all` to `docker run`)
`:ollama`	Bundles Ollama inside the container for an all-in-one setup

Specific release versions

For production environments, pin a specific version instead of using floating tags:

docker pull ghcr.io/hrida-ai/hrida-ai-studio:v1.0.0
docker pull ghcr.io/hrida-ai/hrida-ai-studio:v1.0.0-cuda
docker pull ghcr.io/hrida-ai/hrida-ai-studio:v1.0.0-ollama

Common Configurations

GPU support (Nvidia)

docker run -d -p 3000:8080 --gpus all -v hrida-ai:/app/backend/data --name hrida-ai ghcr.io/hrida-ai/hrida-ai-studio:cuda

Bundled with Ollama

A single container with Hrida.ai and Ollama together:

With GPU:

docker run -d -p 3000:8080 --gpus=all -v ollama:/root/.ollama -v hrida-ai:/app/backend/data --name hrida-ai --restart always ghcr.io/hrida-ai/hrida-ai-studio:ollama

CPU only:

docker run -d -p 3000:8080 -v ollama:/root/.ollama -v hrida-ai:/app/backend/data --name hrida-ai --restart always ghcr.io/hrida-ai/hrida-ai-studio:ollama

Connecting to Ollama on a different server

docker run -d -p 3000:8080 -e OLLAMA_BASE_URL=https://example.com -v hrida-ai:/app/backend/data --name hrida-ai --restart always ghcr.io/hrida-ai/hrida-ai-studio:main

docker run -d -p 3000:8080 -e HRIDAAI_AUTH=False -v hrida-ai:/app/backend/data --name hrida-ai ghcr.io/hrida-ai/hrida-ai-studio:main

warning

You cannot switch between single-user mode and multi-account mode after this change.

Using the Dev Branch

The :dev tag contains the latest features before they reach a stable release.

docker run -d -p 3000:8080 -v hrida-ai:/app/backend/data --name hrida-ai --restart always ghcr.io/hrida-ai/hrida-ai-studio:dev

warning

Never share your data volume between dev and production. Dev builds may include database migrations that are not backward-compatible. Always use a separate volume (e.g., -v hrida-ai-dev:/app/backend/data).

If Docker is not your preference, follow the Developing Hrida.ai.

Uninstall

Stop and remove the container:
```
docker rm -f hrida-ai
```

Remove the image (optional):

docker rmi ghcr.io/hrida-ai/hrida-ai-studio:main

Remove the volume (optional, deletes all data):
```
docker volume rm hrida-ai
```

Updating

To update your local Docker installation to the latest version, you can either use Watchtower or manually update the container.

Option 1: Using Watchtower

With Watchtower, you can automate the update process:

docker run --rm --volume /var/run/docker.sock:/var/run/docker.sock nickfedor/watchtower --run-once hrida-ai

(Replace hrida-ai with your container's name if it's different.)

Option 2: Manual Update

Stop and remove the current container:
```
docker rm -f hrida-ai
```

Pull the latest version:

docker pull ghcr.io/hrida-ai/hrida-ai-studio:main

Start the container again:

docker run -d -p 3000:8080 -v hrida-ai:/app/backend/data \
  -e HRIDAAI_SECRET_KEY="your-secret-key" \
  --name hrida-ai --restart always \
  ghcr.io/hrida-ai/hrida-ai-studio:main

Set HRIDAAI_SECRET_KEY

Without a persistent HRIDAAI_SECRET_KEY, you'll be logged out every time the container is recreated. Generate one with openssl rand -hex 32.

For version pinning, rollback, automated update tools, and backup procedures, see the full update guide.

Docker Compose Setup

Using Docker Compose simplifies the management of multi-container Docker applications.

Docker Compose requires an additional package, docker-compose-v2.

warning

Warning: Older Docker Compose tutorials may reference version 1 syntax, which uses commands like docker-compose build. Ensure you use version 2 syntax, which uses commands like docker compose build (note the space instead of a hyphen).

Example `docker-compose.yml`

Here is an example configuration file for setting up Hrida.ai with Docker Compose:

services:
  hrida-ai:
    image: ghcr.io/hrida-ai/hrida-ai-studio:main
    ports:
      - "3000:8080"
    volumes:
      - hrida-ai:/app/backend/data
volumes:
  hrida-ai:

Using Slim Images

For environments with limited storage or bandwidth, you can use the slim image variant that excludes pre-bundled models:

services:
  hrida-ai:
    image: ghcr.io/hrida-ai/hrida-ai-studio:main-slim
    ports:
      - "3000:8080"
    volumes:
      - hrida-ai:/app/backend/data
volumes:
  hrida-ai:

note

Note: Slim images download required models (whisper, embedding models) on first use, which may result in longer initial startup times but significantly smaller image sizes.

Starting the Services

To start your services, run the following command:

docker compose up -d

Helper Scripts

A set of helper scripts is included with the codebase to streamline common Docker workflows:

run-compose.sh — Interactive Compose launcher with GPU auto-detection and configurable Hrida.ai/API ports. Run ./run-compose.sh --help for the full list of flags. Use --drop to tear down the project.
confirm_remove.sh — Stops the Compose project and deletes all volumes, including persistent data. Prompts for confirmation before destroying data.
run.sh — Builds the Hrida.ai image and runs a single container on port 3000.
run-ollama-docker.sh — Pulls and runs the official Ollama container with optional GPU passthrough, on port 11434.
update_ollama_models.sh — Iterates through every model installed in the Ollama container and pulls the latest version.

note

Note: For Nvidia GPU support, you change the image from ghcr.io/hrida-ai/hrida-ai-studio:main to ghcr.io/hrida-ai/hrida-ai-studio:cuda and add the following to your service definition in the docker-compose.yml file:

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          count: all
          capabilities: [gpu]

This setup ensures that your application can leverage GPU resources when available.

Uninstall

To uninstall Hrida.ai running with Docker Compose, follow these steps:

Stop and Remove the Services: Run this command in the directory containing your docker-compose.yml file:
```
docker compose down
```
Remove the Volume (Optional, WARNING: Deletes all data): If you want to completely remove your data (chats, settings, etc.):
```
docker compose down -v
```
Or manually:
```
docker volume rm <your_project_name>_hrida-ai
```

Remove the Image (Optional):

docker rmi ghcr.io/hrida-ai/hrida-ai-studio:main

Using Podman

Podman is a daemonless container engine for developing, managing, and running OCI Containers.

Basic Commands

Run a Container:

podman run -d --name hridaai -p 3000:8080 -v hrida-ai:/app/backend/data ghcr.io/hrida-ai/hrida-ai-studio:main

List Running Containers:
```
podman ps
```

Networking with Podman

If networking issues arise (specifically on rootless Podman), you may need to adjust the network bridge settings.

Slirp4netns Deprecation

Older Podman instructions often recommended slirp4netns. However, slirp4netns is being deprecated and will be removed in Podman 6.

The modern successor is pasta, which is the default in Podman 5.0+.

Accessing the Host (Local Services)

If you are running Ollama or other services directly on your host machine, use the special DNS name host.containers.internal to point to your computer.

Modern Approach (Pasta - Default in Podman 5+)

No special flags are usually needed to access the host via host.containers.internal.

Legacy Approach (Slirp4netns)

If you are on an older version of Podman and pasta is not available:

Ensure you have slirp4netns installed.
Start the container with the following flag to allow host loopback:

podman run -d --network=slirp4netns:allow_host_loopback=true --name hridaai -p 3000:8080 -v hrida-ai:/app/backend/data ghcr.io/hrida-ai/hrida-ai-studio:main

Connection Configuration

Once inside Hrida.ai, navigate to Settings > Admin Settings > Connections and set your Ollama API connection to: http://host.containers.internal:11434

Refer to the Podman documentation for advanced configurations.

Uninstall

To uninstall Hrida.ai running with Podman, follow these steps:

Stop and Remove the Container:
```
podman rm -f hridaai
```

Remove the Image (Optional):

podman rmi ghcr.io/hrida-ai/hrida-ai-studio:main

Remove the Volume (Optional, WARNING: Deletes all data): If you want to completely remove your data (chats, settings, etc.):
```
podman volume rm hrida-ai
```

Podman Quadlets (systemd)

Podman Quadlets allow you to manage containers as native systemd services. This is the recommended way to run production containers on Linux distributions that use systemd (like Fedora, RHEL, Ubuntu, etc.).

Setup

Create the configuration directory: For a rootless user deployment:
```
mkdir -p ~/.config/containers/systemd/
```

Create the container file: Create a file named ~/.config/containers/systemd/hrida-ai.container with the following content:

[Unit]
Description=Hrida.ai Container
After=network-online.target

[Container]
Image=ghcr.io/hrida-ai/hrida-ai-studio:main
ContainerName=hrida-ai
PublishPort=3000:8080
Volume=hrida-ai:/app/backend/data

# Networking: Pasta is used by default in Podman 5+
# If you need to access host services (like Ollama on the host):
AddHost=host.containers.internal:host-gateway

[Service]
Restart=always

[Install]
WantedBy=default.target

Reload systemd and start the service:

systemctl --user daemon-reload
systemctl --user start hrida-ai

Enable auto-start on boot:
```
systemctl --user enable hrida-ai
```

Management

Check status:
```
systemctl --user status hrida-ai
```
View logs:
```
journalctl --user -u hrida-ai -f
```
Stop service:
```
systemctl --user stop hrida-ai
```

Updating

To update the image, simply pull the new version (podman pull ghcr.io/hrida-ai/hrida-ai-studio:main) and restart the service (systemctl --user restart hrida-ai).

Podman Kube Play Setup

Podman supports Kubernetes like-syntax for deploying resources such as pods, volumes without having the overhead of a full Kubernetes cluster. More about Kube Play.

If you don't have Podman installed, check out Podman's official website.

Example `play.yaml`

Here is an example of a Podman Kube Play file to deploy:

apiVersion: v1
kind: Pod
metadata:
  name: hrida-ai
spec:
  containers:
    - name: container
      image: ghcr.io/hrida-ai/hrida-ai-studio:main
      ports:
        - name: http
          containerPort: 8080
          hostPort: 3000
      volumeMounts:
        - mountPath: /app/backend/data
          name: data
  volumes:
    - name: data
      persistentVolumeClaim:
        claimName:  hrida-ai-pvc
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: hrida-ai-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 5Gi

Starting

To start your pod, run the following command:

podman kube play ./play.yaml

Using GPU Support

For Nvidia GPU support, you need to replace the container image with ghcr.io/hrida-ai/hrida-ai-studio:cuda and need to specify the device (GPU) required in the pod resources limits as followed:

      [...]
      resources:
        limits:
          nvidia.com/gpu=all: 1
      [...]

important

To successfully have the hrida-ai container access the GPU(s), you will need to have the Container Device Interface (CDI) for the GPU you wish to access installed in your Podman Machine. You can check Podman GPU container access.

Docker Swarm

This installation method requires knowledge of Docker Swarm, as it utilizes a stack file to deploy 3 separate containers as services in a Docker Swarm.

It includes isolated containers of ChromaDB, Ollama, and Hrida.ai. Additionally, there are pre-filled Environment Variables to further illustrate the setup.

Why ChromaDB Runs as a Separate Container

This stack correctly deploys ChromaDB as a separate HTTP server container, with Hrida.ai connecting to it via CHROMA_HTTP_HOST and CHROMA_HTTP_PORT. This is required for any multi-worker or multi-replica deployment.

The default ChromaDB mode (without CHROMA_HTTP_HOST) uses a local SQLite-backed PersistentClient that is not fork-safe — concurrent writes from multiple worker processes will crash workers instantly. Running ChromaDB as a separate server avoids this by using HTTP connections instead of direct SQLite access.

If you plan to scale the hridaAI service to multiple replicas, you should also switch to PostgreSQL for the main database and set up Redis. See the Scaling & HA guide for full requirements.

Choose the appropriate command based on your hardware setup:

Before Starting:

Directories for your volumes need to be created on the host, or you can specify a custom location or volume.

The current example utilizes an isolated dir data, which is within the same dir as the docker-stack.yaml.
- For example:
```
mkdir -p data/hrida-ai data/chromadb data/ollama
```
With GPU Support:

Docker-stack.yaml

services:
  hrida-ai:
    image: ghcr.io/hrida-ai/hrida-ai-studio:main
    depends_on:
        - chromadb
        - ollama
    volumes:
      - ./data/hrida-ai:/app/backend/data
    environment:
      DATA_DIR: /app/backend/data
      OLLAMA_BASE_URLS: http://ollama:11434
      CHROMA_HTTP_PORT: 8000
      CHROMA_HTTP_HOST: chromadb
      CHROMA_TENANT: default_tenant
      VECTOR_DB: chroma
      HRIDAAI_NAME: Awesome ChatBot
      CORS_ALLOW_ORIGIN: "*" # This is the current Default, will need to change before going live
      RAG_EMBEDDING_ENGINE: ollama
      RAG_EMBEDDING_MODEL: nomic-embed-text-v1.5
      RAG_EMBEDDING_MODEL_TRUST_REMOTE_CODE: "True"
    ports:
      - target: 8080
        published: 8080
        mode: overlay
    deploy:
      replicas: 1
      restart_policy:
        condition: any
        delay: 5s
        max_attempts: 3

  chromadb:
    hostname: chromadb
    image: chromadb/chroma:0.5.15
    volumes:
      - ./data/chromadb:/chroma/chroma
    environment:
      - IS_PERSISTENT=TRUE
      - ALLOW_RESET=TRUE
      - PERSIST_DIRECTORY=/chroma/chroma
    ports:
      - target: 8000
        published: 8000
        mode: overlay
    deploy:
      replicas: 1
      restart_policy:
        condition: any
        delay: 5s
        max_attempts: 3
    healthcheck:
      test: ["CMD-SHELL", "curl localhost:8000/api/v1/heartbeat || exit 1"]
      interval: 10s
      retries: 2
      start_period: 5s
      timeout: 10s

  ollama:
    image: ollama/ollama:latest
    hostname: ollama
    ports:
      - target: 11434
        published: 11434
        mode: overlay
    deploy:
      resources:
        reservations:
          generic_resources:
            - discrete_resource_spec:
                kind: "NVIDIA-GPU"
                value: 0
      replicas: 1
      restart_policy:
        condition: any
        delay: 5s
        max_attempts: 3
    volumes:
      - ./data/ollama:/root/.ollama

Additional Requirements:
1. Ensure CUDA is Enabled, follow your OS and GPU instructions for that.
2. Enable Docker GPU support, see Nvidia Container Toolkit
- Ensure GPU Resource is enabled in /etc/nvidia-container-runtime/config.toml and enable GPU resource advertising by uncommenting the swarm-resource = "DOCKER_RESOURCE_GPU". The docker daemon must be restarted after updating these files on each node.

With CPU Support:

Modify the Ollama Service within docker-stack.yaml and remove the lines for generic_resources:

    ollama:
  image: ollama/ollama:latest
  hostname: ollama
  ports:
    - target: 11434
      published: 11434
      mode: overlay
  deploy:
    replicas: 1
    restart_policy:
      condition: any
      delay: 5s
      max_attempts: 3
  volumes:
    - ./data/ollama:/root/.ollama

Deploy Docker Stack:

docker stack deploy -c docker-stack.yaml -d super-awesome-ai

Using Docker with WSL (Windows Subsystem for Linux)

This guide provides instructions for setting up Docker and running Hrida.ai in a Windows Subsystem for Linux (WSL) environment.

Step 1: Install WSL

If you haven't already, install WSL by following the official Microsoft documentation:

Install WSL

Step 2: Install Docker Desktop

Docker Desktop is the easiest way to get Docker running in a WSL environment. It handles the integration between Windows and WSL automatically.

Download Docker Desktop: https://www.docker.com/products/docker-desktop/
Install Docker Desktop: Follow the installation instructions, making sure to select the "WSL 2" backend during the setup process.

Step 3: Configure Docker Desktop for WSL

Open Docker Desktop: Start the Docker Desktop application.
Enable WSL Integration:
- Go to Settings > Resources > WSL Integration.
- Make sure the "Enable integration with my default WSL distro" checkbox is selected.
- If you are using a non-default WSL distribution, select it from the list.

Step 4: Run Hrida.ai

Now you can run Hrida.ai by following the standard Docker instructions from within your WSL terminal.

docker pull ghcr.io/hrida-ai/hrida-ai-studio:main
docker run -d -p 3000:8080 -v hrida-ai:/app/backend/data --name hrida-ai ghcr.io/hrida-ai/hrida-ai-studio:main

Important Notes

Run Docker Commands in WSL: Always run docker commands from your WSL terminal, not from PowerShell or Command Prompt.
File System Access: When using volume mounts (-v), make sure the paths are accessible from your WSL distribution.

Python version compatibility

Hrida.ai supports Python 3.11 and 3.12. Python 3.13 is not supported yet — a handful of our dependencies still need to ship 3.13-compatible releases, and until they do, installs on 3.13 will fail or break at runtime.

For production, run the Docker image or use the latest Python 3.11. This is the combination we test against most heavily.
Python 3.12 also works, but we have seen very rare reports of odd behavior on 3.12 that we have not reproduced on 3.11. If something inexplicable happens on 3.12, drop to the latest 3.11 first.

pip
uv
Conda
Venv

Installation with pip

The simplest way to install Hrida.ai with Python.

1. Install Hrida.ai

pip install hrida-ai-studio

2. Start the server

hrida-ai-studio serve

Hrida.ai is now running at http://localhost:8080.

'hrida-ai: command not found'?

If you used a virtual environment, make sure it's activated.
Try running directly: python -m hridaai serve
To store data in a specific location: DATA_DIR=./data hrida-ai-studio serve

Uninstall

Uninstall the package:
```
pip uninstall hrida-ai-studio
```
Remove data (optional, deletes all data):
```
rm -rf ~/.hrida-ai
```

Updating with Python

To update your locally installed hrida-ai package to the latest version using pip, follow these simple steps:

pip install -U hrida-ai-studio

The -U (or --upgrade) flag ensures that pip upgrades the package to the latest available version.

After upgrading, restart the server and verify it starts correctly:

hrida-ai-studio serve

Multi-Worker Environments

If you run Hrida.ai with UVICORN_WORKERS > 1 (e.g., in a production environment), you MUST ensure the update migration runs on a single worker first to prevent database schema corruption.

Steps for proper update:

Update hrida-ai using pip.
Start the application with UVICORN_WORKERS=1 environment variable set.
Wait for the application to fully start and complete migrations.
Stop and restart the application with your desired number of workers.

For version pinning, rollback, and backup procedures, see the full update guide.

Installation with `uv`

The uv runtime manager ensures seamless Python environment management for applications like Hrida.ai. Follow these steps to get started:

1. Install `uv`

Pick the appropriate installation command for your operating system:

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Run Hrida.ai

Once uv is installed, running Hrida.ai is a breeze. Use the command below, ensuring to set the DATA_DIR environment variable to avoid data loss. Example paths are provided for each platform:

macOS/Linux:

DATA_DIR=~/.hrida-ai uvx --python 3.11 hrida-ai-studio@latest serve

Windows (PowerShell):

$env:DATA_DIR="C:\hrida-ai\data"; uvx --python 3.11 hrida-ai-studio@latest serve

Why set DATA_DIR?

Setting DATA_DIR ensures your chats and settings are saved in a predictable location. If you don't set it, uvx might store it in a temporary folder that gets deleted when the process ends.

Uninstall

To remove Hrida.ai when running with uvx:

Stop the Server: Press Ctrl+C in the terminal where it's running.
Uninstall from UV: Enter uv tool uninstall hrida-ai
Available cleanup commands: The uvx command runs the application ephemerally or from cache. To remove cached components:
```
uv cache clean
```
Remove Data (WARNING: Deletes all data): Delete your data directory (default is ~/.hrida-ai or the path set in DATA_DIR):
```
rm -rf ~/.hrida-ai
```

Updating with Python

To update your locally installed hrida-ai package to the latest version using pip, follow these simple steps:

pip install -U hrida-ai-studio

The -U (or --upgrade) flag ensures that pip upgrades the package to the latest available version.

After upgrading, restart the server and verify it starts correctly:

hrida-ai-studio serve

Multi-Worker Environments

If you run Hrida.ai with UVICORN_WORKERS > 1 (e.g., in a production environment), you MUST ensure the update migration runs on a single worker first to prevent database schema corruption.

Steps for proper update:

Update hrida-ai using pip.
Start the application with UVICORN_WORKERS=1 environment variable set.
Wait for the application to fully start and complete migrations.
Stop and restart the application with your desired number of workers.

For version pinning, rollback, and backup procedures, see the full update guide.

Install with Conda

Create a Conda Environment:
```
conda create -n hrida-ai python=3.11
```
Activate the Environment:
```
conda activate hrida-ai
```
Install Hrida.ai:
```
pip install hrida-ai-studio
```
Start the Server:
```
hrida-ai-studio serve
```

'hrida-ai: command not found'?

If your terminal says the command doesn't exist:

Ensure your conda environment is activated (conda activate hrida-ai).
If you still get an error, try running it via Python directly: python -m hridaai serve
If you want to store your data in a specific place, use (Linux/Mac): DATA_DIR=./data hrida-ai-studio serve or (Windows): $env:DATA_DIR=".\data"; hrida-ai-studio serve

Uninstall

Remove the Conda Environment:
```
conda remove --name hrida-ai --all
```
Remove Data (WARNING: Deletes all data): Delete your data directory (usually ~/.hrida-ai unless configured otherwise):
```
rm -rf ~/.hrida-ai
```

Updating with Python

To update your locally installed hrida-ai package to the latest version using pip, follow these simple steps:

pip install -U hrida-ai-studio

The -U (or --upgrade) flag ensures that pip upgrades the package to the latest available version.

After upgrading, restart the server and verify it starts correctly:

hrida-ai-studio serve

Multi-Worker Environments

If you run Hrida.ai with UVICORN_WORKERS > 1 (e.g., in a production environment), you MUST ensure the update migration runs on a single worker first to prevent database schema corruption.

Steps for proper update:

Update hrida-ai using pip.
Start the application with UVICORN_WORKERS=1 environment variable set.
Wait for the application to fully start and complete migrations.
Stop and restart the application with your desired number of workers.

For version pinning, rollback, and backup procedures, see the full update guide.

Using Virtual Environments

Create isolated Python environments using venv.

Venv Steps

Create a Virtual Environment:
```
python3 -m venv venv
```
Activate the Virtual Environment:
- On Linux/macOS:
```
source venv/bin/activate
```
- On Windows:
```
venv\Scripts\activate
```
Install Hrida.ai:
```
pip install hrida-ai-studio
```
Start the Server:
```
hrida-ai-studio serve
```

'hrida-ai: command not found'?

If your terminal says the command doesn't exist:

Ensure your virtual environment is activated (Step 2).
If you still get an error, try running it via Python directly: python -m hridaai serve
If you want to store your data in a specific place, use: DATA_DIR=./data hrida-ai-studio serve

Uninstall

Delete the Virtual Environment: Simply remove the venv folder:
```
rm -rf venv
```
Remove Data (WARNING: Deletes all data): Delete your data directory (usually ~/.hrida-ai unless configured otherwise):
```
rm -rf ~/.hrida-ai
```

Updating with Python

To update your locally installed hrida-ai package to the latest version using pip, follow these simple steps:

pip install -U hrida-ai-studio

The -U (or --upgrade) flag ensures that pip upgrades the package to the latest available version.

After upgrading, restart the server and verify it starts correctly:

hrida-ai-studio serve

Multi-Worker Environments

If you run Hrida.ai with UVICORN_WORKERS > 1 (e.g., in a production environment), you MUST ensure the update migration runs on a single worker first to prevent database schema corruption.

Steps for proper update:

Update hrida-ai using pip.
Start the application with UVICORN_WORKERS=1 environment variable set.
Wait for the application to fully start and complete migrations.
Stop and restart the application with your desired number of workers.

For version pinning, rollback, and backup procedures, see the full update guide.

Helm

Helm Setup for Kubernetes

Helm helps you manage Kubernetes applications.

Prerequisites

Kubernetes cluster is set up.
Helm is installed.

Helm Steps

Add Hrida.ai Helm Repository:

helm repo add hrida-ai https://helm.hrida.ai/
helm repo update

Install Hrida.ai Chart:
```
helm install hridaai hrida-ai/hrida-ai
```
Verify Installation:
```
kubectl get pods
```

warning

If you intend to scale Hrida.ai using multiple nodes/pods/workers in a clustered environment, you need to setup a NoSQL key-value database (Redis). There are some environment variables that need to be set to the same value for all service-instances, otherwise consistency problems, faulty sessions and other issues will occur!

Important: The default vector database (ChromaDB) uses a local SQLite-backed client that is not safe for multi-replica or multi-worker deployments. SQLite connections are not fork-safe, and concurrent writes from multiple processes will crash workers instantly. You must switch to an external vector database (PGVector, Milvus, Qdrant) via VECTOR_DB, or run ChromaDB as a separate HTTP server via CHROMA_HTTP_HOST.

For the complete step-by-step scaling walkthrough, see Deployment & Scaling. For troubleshooting multi-replica issues, see the Scaling & HA guide.

Critical for Updates

If you run Hrida.ai with multiple replicas/pods (replicaCount > 1) or UVICORN_WORKERS > 1, you MUST scale down to a single replica/pod during updates.

Scale down deployment to 1 replica.
Apply the update (new image version).
Wait for the pod to be fully ready (database migrations complete).
Scale back up to your desired replica count.

Failure to do this can result in database corruption due to concurrent migrations.

Access the Hrida.ai

You can access Hrida.ai by port-forwarding or configuring an Ingress.

Ingress Configuration (Nginx)

If you are using the NGINX Ingress Controller, you can enable session affinity (sticky sessions) to improve WebSocket stability. Add the following annotation to your Ingress resource:

metadata:
  annotations:
    nginx.ingress.kubernetes.io/affinity: "cookie"
    nginx.ingress.kubernetes.io/session-cookie-name: "hrida-ai-session"
    nginx.ingress.kubernetes.io/session-cookie-expires: "172800"
    nginx.ingress.kubernetes.io/session-cookie-max-age: "172800"

This ensures that a user's session remains connected to the same pod, reducing issues with WebSocket connections in multi-replica setups (though correct Redis configuration makes this less critical).

Uninstall

Uninstall the Helm Release:
```
helm uninstall hridaai
```
Remove Persistent Volume Claims (WARNING: Deletes all data): Helm does not automatically delete PVCs to prevent accidental data loss. You must delete them manually if you want to wipe everything.
```
kubectl delete pvc -l app.kubernetes.io/instance=hridaai
```

First Login

Admin account: The first account created gets Administrator privileges and controls user management and system settings.
New sign-ups: Subsequent registrations start with Pending status and require Administrator approval.
Privacy: All data, including login details, is stored locally on your device by default. Hrida.ai does not make external requests by default. All models are private by default and must be explicitly shared.

Connect a Model Provider

Hrida.ai needs at least one model provider to start chatting. Choose yours:

LocalAI (local models)→OpenAI→Any OpenAI-compatible API→Claude→

What's Next

New to Hrida.ai? If this is your first time with Hrida.ai, read the Hrida.ai Essentials guide next. It covers the six things every new user needs to know: plugins, tool calling, task models, context management, RAG, and Hrida Terminal.

Explore Features — Once connected, explore what Hrida.ai can do: Features Overview →

Quick Start

Quick Start with Docker​

1. Pull the image​

2. Run the container​

3. Open the UI​

Image Variants​

Specific release versions​

Common Configurations​

GPU support (Nvidia)​

Bundled with Ollama​

Connecting to Ollama on a different server​

Single-user mode (no login)​

Using the Dev Branch​

Uninstall​

Updating​

Option 1: Using Watchtower​

Option 2: Manual Update​

Example docker-compose.yml​

Using Slim Images​

Starting the Services​

Helper Scripts​

Uninstall​

Basic Commands​

Networking with Podman​

Accessing the Host (Local Services)​

Modern Approach (Pasta - Default in Podman 5+)​

Legacy Approach (Slirp4netns)​

Connection Configuration​

Uninstall​

Setup​

Management​

Example play.yaml​

Starting​

Using GPU Support​

Docker Swarm​

Docker-stack.yaml​

Using Docker with WSL (Windows Subsystem for Linux)​

Step 1: Install WSL​

Step 2: Install Docker Desktop​

Step 3: Configure Docker Desktop for WSL​

Step 4: Run Hrida.ai​

Important Notes​

Installation with pip​

1. Install Hrida.ai​

2. Start the server​

Uninstall​

Installation with uv​

1. Install uv​

2. Run Hrida.ai​

Uninstall​

Uninstall​

Venv Steps​

Uninstall​

Prerequisites​

Helm Steps​

Access the Hrida.ai​

Ingress Configuration (Nginx)​

Uninstall​

Desktop App​

Pinokio.computer Installation​

Connect a Model Provider

What's Next

Quick Start with Docker

1. Pull the image

2. Run the container

3. Open the UI

Image Variants

Specific release versions

Common Configurations

GPU support (Nvidia)

Bundled with Ollama

Connecting to Ollama on a different server

Single-user mode (no login)

Using the Dev Branch

Uninstall

Updating

Option 1: Using Watchtower

Option 2: Manual Update

Example `docker-compose.yml`

Using Slim Images

Starting the Services

Helper Scripts

Uninstall

Basic Commands

Networking with Podman

Accessing the Host (Local Services)

Modern Approach (Pasta - Default in Podman 5+)

Legacy Approach (Slirp4netns)

Connection Configuration

Uninstall

Setup

Management

Example `play.yaml`

Starting

Using GPU Support

Docker Swarm

Docker-stack.yaml

Using Docker with WSL (Windows Subsystem for Linux)

Step 1: Install WSL

Step 2: Install Docker Desktop

Step 3: Configure Docker Desktop for WSL

Step 4: Run Hrida.ai

Important Notes

Installation with pip

1. Install Hrida.ai

2. Start the server

Uninstall

Installation with `uv`

1. Install `uv`

2. Run Hrida.ai

Uninstall

Uninstall

Venv Steps

Uninstall

Prerequisites

Helm Steps

Access the Hrida.ai

Ingress Configuration (Nginx)

Uninstall

Desktop App

Pinokio.computer Installation