Run Your Own AI Chat Platform with Onyx in Minutes

// Before you start

What you need

A Linux or macOS machine (Windows users need WSL2)
Docker and Docker Compose installed
At least 4 GB RAM free (8 GB recommended for Standard mode)
An API key from any LLM provider (OpenAI, Anthropic, Gemini, etc.) OR a local Ollama setup
Basic comfort running commands in a terminal

Step 1 of 6

Run the one-line installer

3 min

Onyx provides an official install script that downloads everything and starts the stack for you. This single command pulls the script from onyx.app and runs it. It will install Docker images and set up all the containers automatically. You do not need to clone any repository manually.

Terminal · mac

$ curl -fsSL https://onyx.app/install_onyx.sh | bash

What you should see

The script prints progress messages as it pulls Docker images. At the end you should see something like 'Onyx is running' with a local URL such as http://localhost:3000.

This might happen

The script fails with 'docker: command not found' or permission errors

Install Docker Desktop (Mac/Windows) or run 'sudo apt install docker.io docker-compose-plugin' on Ubuntu, then re-run the install command. On Linux you may need to prefix with 'sudo'.

Step 2 of 6

Open the Onyx web UI and create your admin account

2 min

Once the containers are running, Onyx is available in your browser. The first person to visit the URL gets to create the admin account. This account controls all settings, connectors, and user management.

Terminal · mac

$ open http://localhost:3000

What you should see

A welcome screen asking you to create an admin email and password. Fill in your details and click 'Create Account'.

This might happen

The page shows a blank screen or 'connection refused'

The containers may still be starting. Wait 60 seconds and refresh. Run 'docker ps' to confirm containers named 'onyx' are listed as 'Up'.

Step 3 of 6

Add your LLM provider API key

3 min

Onyx is just the interface — it needs an LLM to power the chat. Go to Settings → LLM Providers in the admin panel and enter your API key. Onyx supports OpenAI, Anthropic, Google Gemini, and many others. If you prefer to run models locally, you can point it at a running Ollama instance instead.

Terminal · mac

$ # No terminal command needed — do this in the browser UI:

$ # Admin Panel → Settings → LLM Providers → Add Provider → paste your API key

What you should see

A green checkmark or 'Provider saved' confirmation message in the UI.

This might happen

The LLM test fails with an authentication error

Double-check that you copied the full API key with no extra spaces. Make sure the key has not expired or hit its usage limit on your provider's dashboard.

Step 4 of 6

Start a chat and verify everything works

2 min

Click 'New Chat' from the sidebar, type a question, and hit send. This confirms your LLM connection is live. You should get a real AI response within a few seconds. If you want web search, toggle the web search icon in the chat toolbar — you will need a Serper or Brave API key in Settings first.

Terminal · mac

$ # In the browser: click 'New Chat' in the left sidebar, type your message, press Enter

What you should see

A streaming AI response appears in the chat window. Response time depends on your chosen LLM provider.

This might happen

Chat sends but returns 'No LLM configured' or an empty response

Go back to Settings → LLM Providers and confirm a default model is selected. Click the star icon next to your provider to set it as default.

Step 5 of 6

Connect a knowledge source (optional but powerful)

5 min

Onyx's RAG feature lets the AI answer questions using your own documents or data. Go to Admin Panel → Connectors and pick a source — Google Drive, Slack, Confluence, a website URL, or just upload files directly. After connecting, Onyx indexes the content in the background. Once indexed, the AI will cite your documents in answers.

Terminal · mac

$ # In the browser:

$ # Admin Panel → Connectors → Add Connector → choose your source → follow the auth steps

What you should see

The connector shows a status of 'Indexing' then 'Completed'. Document count increases in the connector dashboard.

This might happen

Indexing stays stuck on 'In Progress' for more than 10 minutes

Check container logs with 'docker logs onyx-background-1' to see error details. Common causes are missing OAuth credentials for the connector or network timeouts.

Step 6 of 6

Stop or restart Onyx

1 min

When you want to shut Onyx down or restart it after a reboot, use these Docker Compose commands from the directory where Onyx was installed (usually ~/onyx or the current folder when you ran the installer).

Terminal · mac

$ # To stop:

$ docker compose down

$ # To start again:

$ docker compose up -d

What you should see

Containers stop or start cleanly. 'docker ps' shows no Onyx containers when stopped, or all containers as 'Up' when started.

This might happen

'docker compose' command not found

Older Docker versions use 'docker-compose' (with a hyphen) instead. Try 'docker-compose down' or 'docker-compose up -d'.

// Status

cooked. baked. worked.

A fully running, self-hosted AI chat platform accessible at http://localhost:3000 with your chosen LLM connected, optional document search via RAG, and a web UI that rivals commercial AI tools.

// the honest bit

The honest part

The one-line installer works well on clean Linux servers and macOS. Windows requires WSL2 and has more friction. The Lite mode (what the installer defaults to) skips the full vector index, so RAG over large document sets needs the Standard deployment — which requires 8+ GB RAM and more Docker containers. Enterprise features (SSO, RBAC, analytics) are behind the paid Enterprise Edition. Self-hosting means you are responsible for updates, backups, and security — Onyx Cloud exists if you want a managed version.