Frequently Asked Questions
Answers to the most common questions about Hrida.ai — support, privacy, configuration, Docker, and more.
A: No. Hrida.ai is a paid, proprietary product licensed by Zlabs Innovation — there is no free tier or free edition. A free demo is available so you can evaluate Hrida.ai before purchasing a license. Contact hello@hrida.ai or visit the Enterprise page to request a demo. See the License page for full licensing terms.
A: Support for Hrida.ai is provided by the Zlabs Innovation team. Contact us at hello@hrida.ai with details about your issue, including your Hrida.ai version, deployment method, model provider, and steps to reproduce the problem. For organizations requiring dedicated SLAs and priority support, see our Enterprise offerings.
A: You can customize the theme, logo, and branding with our Enterprise License, which unlocks exclusive enterprise features.
For more details on enterprise solutions and branding customizations, click here.
A: Hrida.ai does not send your data to external services by default. If you connect an external model provider, prompts and responses are sent to that provider as needed to generate responses. Everything else runs and is stored locally on your machine or server. If you ever notice anything concerning about how your data is handled, please report it to the Zlabs Innovation team immediately via our Security Policy.
A: Hrida.ai provides a centralized Shared Chats dashboard where you can see every link you've generated. This is available to all users via Settings > Data Controls > Shared Chats > Manage. From there, you can search through your shared history, re-copy links, or revoke (unshare) access to any conversation instantly.
A: You can access the File Manager by going to Settings > Data Controls > Manage Files > Manage. This dashboard allows you to search through all your uploaded documents, view their details, and delete them. Deleting a file here also automatically cleans up any associated Knowledge Base entries and vector embeddings.
A: This error comes from the model provider, not from Hrida.ai — the provider counts the tokens of everything you sent (system prompt + the entire chat history + attached files + tool calls + your new message) and rejects the request once it exceeds the model's context window. The "prompt" the model sees is the whole conversation, not just your latest message.
Hrida.ai intentionally does not ship a built-in context trimmer. Every model has a different tokenizer and a different context window, and every deployment wants a different truncation policy (by tokens, by turns, by message count, file-attachments-first, summarize-and-replace, per-model budgets, and so on). There is no single policy that is correct for every user, so we expose the hook instead of choosing one for you.
Context management is done with filter Functions: inlet() receives the full body["messages"] on every request and can modify it freely (drop old turns, enforce a turn limit, summarize, trim attachments, etc.). Many ready-to-use context filters are available one-click on hrida.ai — browse, install, and tune the valves. If none fits, copy the closest one into Admin Panel ? Functions and edit it.
For the full write-up with examples, see Context Window / Prompt Too Long.
A: Yes. Hrida.ai is a self-hosted, internet-independent AI platform designed to work in air-gapped networks, remote deployments, and any environment where cloud-based systems are impractical or impossible. Whether you need to run an LLM without internet, deploy a private AI with no cloud dependency, or operate a local AI chatbot offline, Hrida.ai supports all of these out of the box. It runs entirely on local hardware and does not make external calls by default.
This Earth-independent architecture is well suited as an AI interface for space exploration — spacecraft, the ISS, lunar bases, Mars habitats, and deep-space missions — where communication delays or total network isolation make cloud AI unworkable. Whether you need self-hosted AI for remote locations or need to run AI in a disconnected environment, Hrida.ai's offline-first design keeps models, tools, and data local and predictable even under extreme latency or complete disconnection.
The same principles apply to harsh terrestrial settings: submarines, polar research stations, underground facilities, air-gapped networks, disaster zones, field operations, and mobile command environments. Hrida.ai serves as an offline AI interface for defense, research, and critical infrastructure where internet access is unavailable, unreliable, or prohibited. If your system can boot and power itself, Hrida.ai is designed to run — no network required.
A: We require you to sign up to become the admin user for enhanced security. This helps protect your instance if it is ever exposed to external access. Hrida.ai does not collect your data. When you sign up, all information is stored locally on your server and is not sent to Hrida.ai or any third party by default.
localhost?A: Inside a Docker container, localhost refers to the container itself, not the host machine. This distinction is crucial for networking. To establish a connection from your container to services running on the host, you should use the DNS name host.docker.internal instead of localhost. This DNS name is specially recognized by Docker to facilitate such connections, effectively treating the host as a reachable entity from within the container, thus bypassing the usual localhost scope limitation.
A: To make services running on the host accessible to Docker containers, configure these services to listen on all network interfaces, using the IP address 0.0.0.0, instead of 127.0.0.1 which is limited to localhost only. This configuration allows the services to accept connections from any IP address, including Docker containers. It's important to be aware of the security implications of this setup, especially when operating in environments with potential external access. Implementing appropriate security measures, such as firewalls and authentication, can help mitigate risks.
A: To update Hrida.ai, you must first pull the latest image, then stop and remove the existing container, and finally start a new one. Simply pulling the image isn't enough because the running container is still based on the old version.
Follow these exact steps:
- Pull the latest image:
docker pull ghcr.io/hrida-ai/hrida-ai-studio:main - Stop and Remove the current container:
docker stop hrida-ai docker rm hrida-ai - Start the new container with your data attached:
docker run -d -p 3000:8080 -v hrida-ai:/app/backend/data --name hrida-ai --restart always ghcr.io/hrida-ai/hrida-ai-studio:main
(Note: If your container or volume has a different name, adjust the commands accordingly.)
For a deeper dive into update methods (including automated updates like Watchtower), check our full Updating Guide.
A: In Docker, containers are meant to be "disposable." Your data is safe only if you have a Volume configured.
If you ran your container without the -v hrida-ai:/app/backend/data flag (or a similar volume mount in Docker Compose), your data is stored inside the container. In that specific case, deleting the container will result in permanent data loss. Always ensure you follow our Quick Start Guide correctly to set up persistent volumes from the beginning.
When you use a Volume (typically named hrida-ai in our examples), your data stays safe even when the container is deleted. When you start a new container and mount that same volume, the new version of the app attaches to your old data automatically.
Default Data Path: On most Linux systems, your volume data is physically stored at: /var/lib/docker/volumes/hrida-ai/_data.
A: We recommend using the official Docker package over distro-packaged versions for running Hrida.ai. The official Docker package is frequently updated with the latest features, bug fixes, and security patches, ensuring optimal performance and security. Additionally, it supports important functionalities like host.docker.internal, which may not be available in distro-packaged versions. This feature is essential for proper network configurations and connectivity within Docker containers.
By choosing the official Docker package, you benefit from consistent behavior across different environments, more reliable troubleshooting support, and access to the latest Docker advancements.
Everything you need to run Hrida.ai, including your data, remains within your server environment. For instructions on installing the official Docker package, please refer to the Install Docker Engine guide on Docker's official documentation site.
A: GPU support in Docker is available but varies depending on the platform. Officially, GPU support is provided in Docker for Windows and Docker Engine on Linux. Other platforms, such as Docker Desktop for Linux and MacOS, do not currently offer GPU support. This limitation is important to consider for applications requiring GPU acceleration. For the best experience and to utilize GPU capabilities, we recommend using Docker on platforms that officially support GPU integration.
A: The decision to use Docker stems from its ability to ensure consistency, isolate dependencies, and simplify deployment across different environments. Docker minimizes compatibility issues and streamlines the process of getting the Hrida.ai up and running, regardless of the underlying system. It's a strategic choice by the project maintainers to harness these benefits, acknowledging that while Docker has a learning curve, the advantages for deployment and maintenance are significant. We understand Docker might not be everyone's preference; however, this approach is central to our project's design and operational efficiency. We view the project's commitment to Docker as a fundamental aspect and encourage those looking for different deployment methods to explore alternative deployment options.
A: The functionality of Speech-to-Text (STT) and Text-to-Speech (TTS) services in your deployment may require HTTPS to operate correctly. Modern browsers enforce security measures that restrict certain features, including STT and TTS, to only work under secure HTTPS connections. If your deployment is not configured to use HTTPS, these services might not function as expected. Ensuring your deployment is accessible over HTTPS can resolve these issues, enabling full functionality of STT/TTS features.
A: While we understand the desire for an all-in-one solution that includes HTTPS support, we believe such an approach wouldn't adequately serve the diverse needs of our user base. Implementing HTTPS directly within the project could limit flexibility and may not align with the specific requirements or preferences of all users. To ensure that everyone can tailor their setup to their unique environment, we leave the implementation of HTTPS termination to the users for their production deployments. This decision allows for greater adaptability and customization. Though we don't offer official documentation on setting up HTTPS, our team may provide guidance upon request.
A: If your Hrida.ai isn't launching post-update or installation of new software, it's likely related to a direct installation approach, especially if you didn't use a virtual environment for your backend dependencies. Direct installations can be sensitive to changes in the system's environment, such as updates or new installations that alter existing dependencies. To avoid conflicts and ensure stability, we recommend using a virtual environment for managing the requirements.txt dependencies of your backend. This isolates your Hrida.ai dependencies from other system packages, minimizing the risk of such issues.
A: This happens because you haven't set a persistent HRIDAAI_SECRET_KEY in your environment variables.
- Logouts: Without this key, Hrida.ai generates a random one every time it starts. This invalidates your previous session cookies (JWTs), forcing you to log in again.
- Decryption Errors: Essential secrets (like OAuth tokens for MCP tools or API keys) are encrypted using this key. If the key changes on restart, Hrida.ai cannot decrypt them, leading to errors.
Fix: Set HRIDAAI_SECRET_KEY to a constant, secure string in your Docker Compose or environment config.
A: This issue typically arises when a Docker container is created without mounting a volume for /app/backend/data or if the designated Hrida.ai volume (usually named hrida-ai in our examples) was unintentionally deleted. Docker volumes are crucial for persisting your data across container lifecycles. If you find yourself needing to create a new account after a restart, it's likely you've initiated a new container without attaching the existing volume where your data resides. Ensure that your Docker run command includes a volume mount pointing to the correct data location to prevent data loss.
A: This situation occurs when you forget the password for the initial admin account created during the first setup. The first account is automatically designated as the admin account. Creating a new account without access to the admin account will result in the need for admin activation. Avoiding the loss of the initial admin account credentials is crucial for seamless access and management of Hrida.ai. See the Resetting the Admin Password guide for instructions on recovering the admin account.
A: The SSL error you're encountering when starting Hrida.ai is likely due to the absence of SSL certificates or incorrect configuration of huggingface.co. To resolve this issue, you could set up a mirror for HuggingFace, such as hf-mirror.com, and specify it as the endpoint when starting the Docker container. Use the -e HF_ENDPOINT=https://hf-mirror.com/ parameter to define the HuggingFace mirror address in the Docker run command. For example, you can modify the Docker run command as follows:
docker run -d -p 3000:8080 -e HF_ENDPOINT=https://hf-mirror.com/ --add-host=host.docker.internal:host-gateway -v hrida-ai:/app/backend/data --name hrida-ai --restart always ghcr.io/hrida-ai/hrida-ai-studio:mainA: This happens if the model's thinking tags are not recognized by Hrida.ai. You can customize the tags in the model's Advanced Parameters. For more details, see the Reasoning & Thinking Models guide.
A: If you're using Ollama, be aware that Ollama sets the context length to 2048 tokens by default. This means that none of the retrieved data might be used because it doesn't fit within the available context window.
To improve the performance of Retrieval-Augmented Generation (RAG) with Hrida.ai, you should increase the context length to a much larger value (8192+ tokens) to ensure that retrieved documents can effectively contribute to the model's responses.
To do this, configure your Ollama model params to allow a larger context window. You can check and modify this setting in your chat directly or from model editor page to enhance the RAG experience significantly.
A: This is a race condition, not an actual empty file. When you upload a file through the API, the endpoint returns immediately with a file ID, but content extraction and embedding computation happen asynchronously in the background.
If you immediately try to add the file to a knowledge base before processing completes, the system sees empty content and returns a 400 error.
Solution: Poll the file status endpoint until processing is complete:
import requests
import time
def wait_for_processing(token, file_id):
url = f'http://localhost:3000/api/v1/files/{file_id}/process/status'
headers = {'Authorization': f'Bearer {token}'}
while True:
status = requests.get(url, headers=headers).json().get('status')
if status == 'completed':
return True
elif status == 'failed':
raise Exception("Processing failed")
time.sleep(2) # Wait before checking againFor complete workflow examples, see the API Endpoints documentation and the RAG Troubleshooting guide.
A: No—LLMs do not reliably know their own identity. When you ask a model "What model are you?" or "Are you GPT-4?", the response is not a system diagnostic. It's simply the model generating text based on patterns in its training data.
Models frequently:
- Claim to be a different model (e.g., a Llama model claiming to be ChatGPT)
- Give outdated information about themselves
- Hallucinate version numbers or capabilities
- Change their answer depending on how you phrase the question
To verify which model you're actually using:
- Check the model selector in the Hrida.ai interface
- Look at the Admin Panel > Settings > Connections to confirm your API endpoints
- Check your provider's dashboard/logs for the actual API calls being made
Asking the model itself is not a valid way to diagnose routing issues. If you suspect a configuration problem, check your connection settings and API keys instead.
A: Because the provider injects a system prompt that explicitly tells the model what it is. When you use ChatGPT, OpenAI's interface includes a hidden system message like "You are ChatGPT, a large language model trained by OpenAI..." before your conversation begins.
The model isn't "aware" of itself—it's simply been instructed to claim a specific identity. You can do the same thing in Hrida.ai by adding a system prompt to your model configuration (e.g., "You are Llama 3.3 70B..."). The model will then confidently repeat whatever identity you've told it to claim.
This is also why the same model accessed through different interfaces might give different answers about its identity—it depends entirely on what system prompt (if any) was provided.
A: Hrida.ai uses Task Models to power background features that enhance your chat experience. When you send a single message, additional API calls may be made for:
- Title Generation: Automatically generating a title for new chats
- Tag Generation: Auto-tagging chats for organization
- Query Generation: Creating optimized search queries for RAG (when you attach files or knowledge)
- Web Search Queries: Generating search terms when web search is enabled
- Autocomplete Suggestions: If enabled
By default, these tasks use the same model you're chatting with. If you're using an expensive API model (like GPT-4 or Claude), this can significantly increase your costs.
To reduce API costs:
- Go to Admin Panel > Settings > Interface (for title/tag generation settings)
- Configure a Task Model under Admin Panel > Settings > Models to use a smaller, cheaper model (like GPT-4o-mini) or a local model for background tasks
- Disable features you don't need (auto-title, auto-tags, etc.)
Set your Task Model to a fast, inexpensive model (or a local model via Ollama) while keeping your primary chat model as a more capable one. This gives you the best of both worlds: smart responses for your conversations, cheap/free processing for background tasks.
For more optimization tips, see the Performance Tips Guide.
A: Yes, Hrida.ai includes native support for MCP Streamable HTTP, enabling direct, first-class integration with MCP tools that communicate over the standard HTTP transport. For any other MCP transports or non-HTTP implementations, you should use our official proxy adapter, MCPO. MCPO provides a unified OpenAPI-compatible layer that bridges alternative MCP transports into Hrida.ai safely and consistently. This architecture ensures maximum compatibility, strict security boundaries, and predictable tool behavior across different environments while keeping Hrida.ai backend-agnostic and maintainable.
Why doesn't Hrida.ai natively support [Provider X]'s proprietary API?
A: Hrida.ai is highly modular with a plugin system including tools, functions, and most notably pipes. These modular pipes allow you to add support for virtually any provider you want—you can build your own or choose from the many third-party and usually well-maintained ones already available.
That said, Hrida.ai's core is built around universal protocols, not specific providers. Our stance is to support standard, widely-adopted APIs like the OpenAI Chat Completions protocol.
This protocol-centric design ensures that Hrida.ai remains backend-agnostic and compatible with dozens of providers simultaneously. We avoid implementing proprietary, provider-specific APIs in the core to prevent unsustainable architectural bloat and to maintain a truly open ecosystem.
As new standards emerge that gain broad adoption, we may add support. Connections can now optionally be configured to use Open Responses—an open specification for multi-provider interoperability with consistent streaming events and tool use patterns.
We understand this request comes up frequently, especially for major providers. Here's why we've made this deliberate architectural decision:
1. The Cascading Demand Problem
Supporting one proprietary API sets a precedent. Once that precedent exists, every other major provider becomes a reasonable request. What starts as "just one provider" quickly becomes many integrations, each with their own quirks, authentication schemes, and breaking changes.
2. Maintenance is the Real Burden
Adding integration code is the easy part. Maintaining it forever is where the real cost lies:
- Each provider updates their API independently—when a provider changes something, we must update and test immediately
- Changes in one integration can break compatibility with others
- Every integration requires ongoing testing across multiple scenarios
- Bug reports flood in for each provider whenever they make changes
Maintaining 10+ provider integrations indefinitely is not sustainable.
3. Technical Complexity
Each provider has different approaches to:
- Reasoning/thinking content format and structure
- Tool calling schemas and response formats
- Authentication and request signing
- Error handling and rate limiting
This requires provider-specific logic throughout both the backend and frontend, significantly increasing the codebase complexity and tech debt.
4. Scale and Stability Requirements
Hrida.ai is used by major organizations worldwide. At this scale, stability is paramount, and extensive testing and backwards compatibility requirements become exponentially harder with each added provider.
5. Pipes are the Modular Solution
The pipes architecture exists precisely to solve this problem. One-click install a plugin and you get full provider API support. This is exactly the modularity that allows:
- independent teams to maintain provider-specific integrations
- Users to choose only what they need
- The core project to remain stable and maintainable
For providers that don't follow widely adopted API standards, use:
• Zlabs Innovation: Provider integrations (one-click install)
• Middleware proxies: Tools like LiteLLM or OpenRouter can translate proprietary APIs to widely adopted API formats
These solutions exist specifically to bridge the gap, and they're maintained by teams dedicated to that purpose.
The assumption that bundling the frontend with the backend is unscalable comes from a misunderstanding of how modern Single-Page Applications work. Hrida.ai's frontend is a static SPA, meaning it consists only of HTML, CSS, and JavaScript files with no runtime coupling to the backend. Because these files are static, lightweight, and require no separate server, including them in the same image has no impact on scalability. This approach simplifies deployment, ensures every replica serves the exact same assets, and eliminates unnecessary moving parts. If you prefer, you can still host the SPA on any CDN or static hosting service and point it to a remote backend, but packaging both together is the standard and most practical method for containerized SPAs.
A: Yes, Hrida.ai is architected for scalability and production readiness. With the right infrastructure, it supports deployments at significant scale—including organizations with tens of thousands of users—across universities, multinational enterprises, and government agencies worldwide. See the Scaling Guide for the infrastructure requirements at each stage.
Hrida.ai's stateless, container-first architecture means you're not limited to a single server. Through horizontal scaling, flexible storage backends, externalized authentication and database support, and full container orchestration compatibility (for example, Kubernetes or Docker Swarm), you can build robust, high-availability clusters to meet even the most demanding enterprise requirements.
With the right infrastructure configuration, Hrida.ai is designed to scale from pilot projects to large-scale rollouts.
A: For organizations with demanding uptime and scale requirements, Hrida.ai is designed to plug into modern production environments:
- Multiple containers (instances) behind a load balancer for resilience and optimal performance
- External databases and persistent storage for scalable, reliable data
- Integration with enterprise authentication (like SSO/OIDC/LDAP) for seamless and secure login
- Observability and monitoring via modern log/metrics tools
If you're planning a high-availability, enterprise-grade deployment, we recommend reviewing this deployment guide:
The SRE's Guide to High Availability Hrida.ai Deployment Architecture
(This provides a strong technical overview and best practices for large-scale Hrida.ai architecture.)
Hrida.ai is designed from day one to not just handle, but thrive at scale—serving large organizations, universities, and enterprises worldwide.
A: We aim to ship major releases weekly, with bug fixes and minor updates delivered as needed. However, this is not a rigid schedule—some weeks may see multiple releases, while others might have none at all.
If you encounter an Hrida.ai deployment that appears to violate the Hrida.ai license—such as removed branding where it is not permitted, misleading white-labeling, commercial misuse, or any form of unauthorized redistribution—you can confidentially report it to our compliance team.
Email: reports@hrida.ai
Please include any relevant details (screenshots, URLs, description of usage, etc.) so we can investigate appropriately.
We review every report in good faith and handle all submissions discreetly. Protecting the health, clarity, and integrity of the Hrida.ai ecosystem helps us keep the project sustainable, fair, and openly accessible for everyone.