Onyx Self-Hosted: Installation, Licensing and Comparison with Open WebUI

Onyx on your own network instead of in the cloud? WZ-IT installs and operates Onyx on your infrastructure, connects data sources and local models and takes care of updates and monitoring. More building blocks in the AI hub. Book an appointment

Onyx is an open source platform that pulls company knowledge from many applications into a shared search index and generates AI answers with source citations on top of it. The project was previously called Danswer. It is one of the few open source tools that ship connectors, syncing and permission inheritance from source systems, which makes it a candidate for a self-hosted alternative to Microsoft 365 Copilot or Atlassian Rovo.

This article summarises what the Community Edition covers and what only the Enterprise Edition offers, which connectors exist, what resources Onyx needs, how the Docker Compose installation works, how local models are connected and how Onyx differs from the Knowledge feature in Open WebUI. All details refer to Onyx 4.8.0, as of September 2026.

Table of Contents

1. What Onyx is
2. Community Edition and Enterprise Edition
3. Connectors and permissions
4. Onyx system requirements
5. Installing Onyx with Docker Compose
6. Connecting local models and embeddings
7. Onyx compared with Open WebUI Knowledge
8. Pitfalls in operation
9. Our approach at WZ-IT
10. Further guides

What Onyx is

Onyx describes itself as the knowledge and context layer for teams and AI agents (Onyx README). The platform pulls content, metadata and permissions from connected applications, stores them in a hybrid index combining vector and keyword search and makes them available through chat, search and agents. An introduction to the principle is available in What is RAG?.

Beyond search and chat, Onyx includes Deep Research, custom agents with scoped knowledge, actions via MCP and OpenAPI, web search (among others via SearXNG) and a sandbox for code. For a company knowledge base, connectors, index and permission model are the core. The remaining features can be added later.

Community Edition and Enterprise Edition

Onyx comes in two editions (Onyx README, Licensing). The boundary is clearly drawn in the repository: code in the ee directories (backend/ee, web/src/app/ee, web/src/ee) is covered by the Onyx Enterprise License, everything else by the MIT license (LICENSE). For self-hosted instances, a license is issued after subscribing to a plan and is stored and validated locally; air-gapped environments are supported via manual license upload (Plans & Billing).

Sources for the table: Plans & Billing, SSO Providers and Enterprise Edition. Current prices are listed at onyx.app/pricing.

The Onyx documentation names organisations with more than 100 users, environments that require SSO and instances that must inherit permissions from external systems as typical candidates for the Enterprise Edition. The last point is the one that decides most often in practice: as soon as content with different read permissions flows into a shared index, the Community Edition only works if knowledge areas are cut in advance so that every user group may see everything in them. The reasons are explained in the article on permissions in RAG systems.

Connectors and permissions

The documentation lists 54 official connectors (Connectors Overview). Nearly all of them sync continuously: by default Onyx fetches changes every 30 minutes and removes content that no longer exists in the source every 30 days. Without a start date, the first run reads the entire history of a source, which according to the documentation can take days for large sources.

The file connector processes uploaded files in TXT, PDF, DOCX, PPTX, XLSX, CSV, Markdown, JSON, XML, YAML, EML, EPUB and further formats, including as a ZIP archive. A metadata line at the top of a file can carry link, owners, update date and custom tags.

Three access types per connector. A connector is private (only the creator plus assigned users and groups), public (all Onyx users) or set to "Auto Sync Permissions". Only in the last case does Onyx carry over the access lists of the source. This permission sync is an Enterprise Edition feature and is available only for these connectors:

What is missing. The official list contains no connector for Nextcloud, WebDAV or SMB shares (as of September 2026). Organisations whose documents live in Nextcloud are left with the web crawler, file upload or a custom connector built on the Onyx API. None of these routes carries over Nextcloud permissions. The general options for Nextcloud, SharePoint and document management systems are covered in the article on RAG data sources, the combination with Open WebUI in RAG with Nextcloud and Open WebUI.

Onyx system requirements

Onyx has two deployment modes (Deployment Overview). Onyx Standard contains the vector and keyword index, background workers for connectors, two model servers for embeddings and reranking as well as Redis and MinIO. Onyx Lite is a chat interface with agents, file uploads and projects, but without an index. For a knowledge base with connectors, only Standard is an option.

Source: Resourcing, as of September 2026. For a Kubernetes deployment, the documentation lists these requirements per service:

In total this comes to around 12 CPU and 24 GB RAM. If embeddings are computed through an external API instead of locally, the two model servers need significantly less memory.

How requirements grow with data volume. The main driver is the amount of indexed documents stored in OpenSearch. On-disk storage for a single node without replicas is roughly 1.45 times the source data. For OpenSearch memory, the documentation gives guidance per GB of source data:

The documentation's worked example: 10 GB of text content means 4 GB base plus 10 × 1.5 GB for OpenSearch, i.e. 19 GB RAM, and 4.5 CPU cores. On a single machine the other services come on top, adding up to at least 9 CPU and 35 GB RAM. The OpenSearch JVM heap should get half of the available memory and must not exceed 32 GB.

These figures cover Onyx only. A local language model runs as a separate service with its own GPU requirements. How much VRAM a given model needs is covered in GPU and VRAM sizing for LLMs.

Installing Onyx with Docker Compose

The documentation describes two ways to install with Docker Compose: the guided installer of the Onyx CLI and the manual setup from the repository.

Option 1: Onyx CLI. The recommended route is onyx-cli deploy install (Quickstart). The install_onyx.sh script only installs the CLI and runs the same command.

uv tool install onyx-cli
onyx-cli deploy install

The installer checks RAM, disk and free ports, installs Docker Engine and the Compose plugin on Linux after confirmation, asks for the deployment mode (Lite or Standard) and the version, creates a .env with randomly generated secrets and starts the containers until all services report healthy (Onyx CLI). The configuration lives in ~/.config/onyx, the data in named Docker volumes.

With --offline, Onyx can be rolled out from images already present on the host without network access. This is the basis for isolated environments.

Option 2: manually from the repository (Docker):

git clone --depth 1 https://github.com/onyx-dot-app/onyx.git
cd onyx/deployment/docker_compose
docker compose up -d

After initialisation, Onyx is reachable on port 3000. The compose file of version 4.8.0 starts these services:

Before going to production. The compose file contains its own checklist (docker-compose.yml). With the manual route, four points in particular remain open:

• Pin the version. The env.template sets IMAGE_TAG=latest. For reproducible operation, a fixed version such as v4.8.0 belongs there.
• Replace passwords. Without the variable set, OpenSearch starts with the default password from the compose file, and MinIO with default credentials. Set OPENSEARCH_ADMIN_PASSWORD, the MinIO credentials and USER_AUTH_SECRET before the first start.
• Close ports. Apart from nginx, no service should listen externally.
• Set up TLS. Either through the prepared Certbot service or a reverse proxy in front.

The CLI generates secrets automatically and is therefore the cleaner route for new installations. For larger environments there is a Helm chart that lets services scale individually.

Connecting local models and embeddings

Onyx separates two kinds of models: the language model for answers and the embedding model for the index.

Language model. Providers are added in the admin panel under "Configuration → Language Models". For operation without a US cloud, three routes are relevant:

For each provider you can define which models are visible and whether it is available to all users or only to specific groups. What a central gateway in front of several models looks like is explained in What is LiteLLM?. If you prefer European model APIs over your own hardware, see the comparison of European LLM APIs.

Embedding model. The embedding model is chosen under "Search Settings" (Index Settings). The source code default is nomic-ai/nomic-embed-text-v1 with 768 dimensions (configs.py), a model trained predominantly on English. The suggested self-hosted models include multilingual variants such as intfloat/multilingual-e5-base and intfloat/multilingual-e5-small (embedding_configs.py); custom models can be connected as well. For German-language content, the choice of embedding model is one of the most important levers, see the comparison of embedding models for German.

Changing the embedding model triggers a full re-index. During the switch, the old model remains active for searches. Model selection therefore belongs at the start of a project, not at the end.

Further search settings. The same page configures reranking, multilingual query expansion, multipass indexing with chunks of different sizes, Contextual RAG and embedding precision (bfloat16 or float). Contextual RAG adds document-level information to every chunk and, according to the documentation, is very expensive to compute. The background is covered in the articles on hybrid search and reranking, contextual retrieval and chunking strategies.

For local embeddings, the Onyx documentation strongly recommends a GPU for the indexing model server. WZ-IT provides managed GPU servers with NVIDIA RTX PRO 4000 Blackwell (24 GB) or RTX PRO 6000 Blackwell (96 GB); for operation on your own network there is the AI Cube.

Onyx compared with Open WebUI Knowledge

Onyx and Open WebUI are often mentioned together but start from different places. Open WebUI is primarily a chat interface for local and remote models whose Knowledge feature ingests documents into knowledge bases (Open WebUI Knowledge). Onyx is primarily a search and knowledge layer across many company sources.

Since version 0.6.6, the Open WebUI license prohibits removing the "Open WebUI" branding, except with 50 or fewer users in 30 days, with written permission or with an enterprise license (Open WebUI License).

When Onyx fits: many sources such as Confluence, Jira, SharePoint and Teams need to be searchable together, content changes continuously, and the read permissions of the source systems must apply in the index. The latter requires the Enterprise Edition.

When Open WebUI fits: chatting with local models is the focus, the knowledge bases are manageable and can be cut per group into separate knowledge bases, and resource use should stay low. A comparison of Open WebUI with AnythingLLM is available in Open WebUI vs. AnythingLLM.

The two tools are not mutually exclusive. Onyx can be attached to other clients as a knowledge source through its MCP server, and Open WebUI can use the same models via a gateway in front of them.

Pitfalls in operation

• Upgrading from old versions. Since version 3, Onyx automatically migrates indexed documents from Vespa to OpenSearch. Jumping from a version before 3 directly to 4 loses the index and requires re-indexing all connectors (OpenSearch Migration). The path therefore always leads through version 3.
• Unpinned images. Without a fixed version, the installation pulls the latest tag. The Onyx documentation recommends staying on the latest stable release and setting versions deliberately. With weekly releases, an update window belongs in the operations plan.
• Full disk. OpenSearch sets indices to read-only at 95 percent disk usage. New documents are then no longer indexed. Disk usage belongs in monitoring.
• Initial indexing. Without a start date, a connector reads the full history of the source. For large Confluence or SharePoint estates, a start date or a pilot with a subset makes sense.
• Public connectors. If a connector with access to confidential areas is set up as public, every Onyx user sees that content. In the Community Edition, the scoping of sources has to replace the permission model.
• Re-indexing on model change. Every change of embedding model rebuilds the index and loads the indexing model server accordingly.

Our approach at WZ-IT

We operate Onyx on your infrastructure or on a managed GPU server run by WZ-IT in Germany. Support, consulting and implementation are provided by WZ-IT.

1. Clarify sources and permissions. Which systems are connected, which areas stay excluded and whether permissions from the source systems must be inherited. This determines the choice between Community and Enterprise Edition.
2. Pilot with real questions. A scoped set of documents with agreed reference questions and source checks, as described in the RAG Proof of Value.
3. Installation and hardening. Onyx via Docker Compose or Kubernetes with pinned versions, own secrets, TLS, SSO and closed ports.
4. Connect models. Local language model via Ollama or vLLM, an embedding model suited to German content, and optionally a gateway via LiteLLM.
5. Ongoing operations. Updates, monitoring of connectors, index and disk usage as well as backups, described on the page Operating Onyx.

If the goal is a chat with knowledge bases rather than a search and agent platform, we use Open WebUI. For a finished assistant with several knowledge areas and roles, there is the internal AI assistant.

Further guides

• Atlassian Rovo alternative self-hosted, wiki and AI layer with permissions under your own control.
• Best embedding models for German, which model finds German documents reliably.
• XWiki AI setup, the XWiki LLM Application with a local model.
• Hybrid search and reranking, why vector search alone is not enough.
• Open WebUI vs. AnythingLLM, the two best-known chat interfaces compared.
• AI solutions by WZ-IT, the hub for local models, GPU servers and RAG.

Introducing Onyx without handing data to third-party clouds? We set up Onyx with your data sources and a local model and, if required, take over ongoing operations. Book an appointment

Sources

• Onyx on GitHub (README)
• Onyx, LICENSE
• Onyx, GitHub Releases
• Onyx Docs, Deployment Overview
• Onyx Docs, Quickstart
• Onyx Docs, Resourcing
• Onyx Docs, Onyx CLI
• Onyx Docs, Docker
• Onyx Docs, Kubernetes
• Onyx Docs, Enterprise Edition
• Onyx Docs, Plans & Billing
• Onyx Docs, SSO Providers
• Onyx Docs, Connectors Overview
• Onyx Docs, File Connector
• Onyx Docs, Create Connectors
• Onyx Docs, Ollama
• Onyx Docs, LiteLLM Proxy
• Onyx Docs, Custom Inference Provider
• Onyx Docs, Index Settings
• Onyx Docs, OpenSearch Document Index Migration
• Onyx Docs, Release Process & Updates
• Onyx, docker-compose.yml
• Onyx, shared_configs/configs.py
• Onyx, embedding_configs.py
• Open WebUI Docs, Knowledge
• Open WebUI Docs, Knowledge Base Sync (oikb)
• Open WebUI Docs, Groups
• Open WebUI Docs, License