How to Deploy the Free Open‑Source Enterprise ChatGPT Platform Onyx – Complete Guide

Overview

Onyx is an open‑source enterprise‑grade Retrieval‑Augmented Generation (RAG) platform that can be self‑hosted and works with any LLM (OpenAI, Anthropic, Google, Ollama, VLLM, Azure). It provides AI chat, intelligent search, custom agents and automation actions.

Key Technical Features

Smart Chat

File/URL chat – upload PDF, DOCX, TXT or paste a URL to fetch content.

Four built‑in actions: internal search, web search, code execution, image generation.

Deep research mode – multi‑turn reasoning; cost may exceed normal inference by >10×.

Model selector – choose any LLM, adjust creativity and reasoning level.

Custom Agents

Agent = instructions + knowledge + actions. Instructions are prompt templates (e.g., “always provide results in tables”). Knowledge comes from connectors or file uploads and syncs automatically. Actions expose external APIs via REST, GraphQL or Model Context Protocol (MCP).

Internal Search

Hybrid search combines semantic and keyword matching.

Contextual retrieval understands query intent.

AI‑generated knowledge graph discovers relationships.

Advanced RAG reduces hallucinations and improves accuracy.

Web Search

External search APIs (Google, Bing) can be called to obtain up‑to‑date information, useful when internal documents are stale.

Actions & MCP

Actions let agents interact with external systems (CRM, monitoring, ticketing) via REST, GraphQL or MCP. Built‑in actions include internal search, web search, code execution and image generation. Custom actions can be added.

Code Execution

Python sandbox enables complex calculations, data analysis, visualization and script automation directly from chat.

System Architecture

Frontend: Next.js, React, TypeScript. Backend: Python, FastAPI. Database: PostgreSQL (user data, sessions, config). Vector store: Qdrant / Weaviate / Milvus (document embeddings). Search engine: Vespa / Elasticsearch (full‑text search). Deployment: Docker, Docker Compose, Kubernetes.

┌─────────────────────────────────────────────┐
│            Onyx Platform                     │
├─────────────────────────────────────────────┤
│  Web UI (Next.js)   API (FastAPI)   Workers │
│                PostgreSQL (user data)       │
│          Vector DB (Qdrant) – embeddings    │
│          Search Engine (Vespa) – full‑text   │
└─────────────────────────────────────────────┘
External integrations: LLM APIs, Connectors, Search APIs

Real‑World Scenarios

Enterprise Knowledge‑Base Q&A

Problem: documents scattered across Confluence, Google Drive, Slack.

Solution: configure connectors, employees ask natural‑language questions.

Result: search time ↓ from 30 min to 2 min; onboarding efficiency ↑ 50 %.

Customer‑Support Automation

Create a “support assistant” agent linked to product docs, FAQs and ticket history.

Configure actions to update ticket status automatically.

Result: 60 % of tickets handled automatically; response time ↓ from 2 h to 5 min.

R&D Knowledge Base

Build an “engineer co‑pilot” agent that connects to GitHub, Jira and internal Wiki.

Enable code‑execution for debugging assistance.

Result: new‑hire ramp‑up ↓ from 2 weeks to 3 days; duplicate questions ↓ 70 %.

Sales Support Assistant

Agent pulls product specs, competitor analysis and past proposals.

Actions auto‑update CRM opportunities and generate custom quotes.

Result: proposal preparation ↓ from 1 day to 1 hour; conversion rate ↑ 25 %.

Competitor Comparison (selected features)

Self‑hosted: Onyx ✅, ChatGPT Enterprise ❌, Microsoft Copilot ❌, Glean ❌.

Open‑source: Onyx ✅, others ❌.

LLM choice: Onyx ✅ any LLM, ChatGPT ⚠️ OpenAI only, Copilot ⚠️ Azure OpenAI only.

Data privacy: Onyx ✅ fully controllable, others ⚠️ vendor‑dependent.

Custom development: Onyx ✅ deep customization, others ❌ limited.

Cost: Onyx 💰 free (self‑hosted), ChatGPT 💰💰💰 $60/user/mo, Copilot 💰💰💰 $30/user/mo.

Agent support: Onyx ✅ full, ChatGPT ⚠️ limited, Copilot ⚠️ limited, Glean ❌.

Code execution: Onyx ✅ built‑in, ChatGPT ❌, Copilot ⚠️ limited, Glean ❌.

Deployment Guide

Hardware Requirements

Lite: 2 CPU cores, 4 GB RAM, 20 GB storage.

Standard: 4 CPU cores, 8 GB RAM, 50 GB storage.

Software Requirements

Docker 20.10+

Docker Compose 2.0+

Git (to pull configuration files)

Installation Steps

# Linux / macOS
curl -fsSL https://onyx.app/install_onyx.sh -o install_onyx.sh
chmod +x install_onyx.sh

# Windows PowerShell
irm https://onyx.app/install_onyx.ps1 -Outfile install_onyx.ps1

# Run the script
bash install_onyx.sh   # Linux/macOS
.\install_onyx.ps1      # Windows

Select deployment type:
1) Lite (personal / small team)
2) Standard (production)
Enter choice [1-2]:

Select Onyx version:
1) Latest (recommended)
2) Stable
3) Specific version
Enter choice [1-3]:

After deployment the UI is available at http://localhost:3000.

Development Environment

# Clone the repository
git clone https://github.com/onyx-dot-app/onyx.git
cd onyx

# Install Python dependencies
pip install -r requirements.txt

# Start development stack
docker compose -f docker-compose.dev.yml up

# Run tests
pytest tests/

LLM Configuration

OpenAI – GPT‑4, GPT‑3.5 – API Key.

Anthropic – Claude 3, Claude 2 – API Key.

Google – Gemini Pro, Gemini Ultra – API Key.

Ollama – Llama 3, Mistral – self‑hosted.

VLLM – any open‑source model – self‑hosted.

Azure – Azure OpenAI – API Key + Endpoint.

Connector Configuration Examples

connector_type: google_drive
credentials: service_account_key.json
include_files: true
include_folders: true

connector_type: confluence
wiki_base: https://your-company.atlassian.net
username: [email protected]
api_token: your_api_token

connector_type: slack
bot_token: xoxb-your-bot-token
channels: ["general", "engineering", "support"]

Security & Compliance

Data at rest encrypted with AES‑256.

Role‑Based Access Control (RBAC).

Audit logging.

SSO support (SAML, OIDC).

VPC‑compatible deployment.

Compliance: SOC 2 Type II, GDPR, ISO 27001; HIPAA available with extra configuration.

Reference Resources

- GitHub repository: https://github.com/onyx-dot-app/onyx
- Documentation: https://docs.onyx.app
- Cloud service: https://cloud.onyx.app
- Community forum: https://community.onyx.app