Skip to main content
Read the Resourcing Guide before you start.
This guide covers managing the Compose files by hand. For a guided install with managed upgrades, use the Onyx CLI instead. The CLI can also adopt a manual setup later.

​
Guide

Note: On Windows, the commands differ slightly, but the steps are the same.
1

Install requirements

2

Clone the Onyx repo

3

Create the .env file

Copy the template and edit the values you need:
IMAGE_TAG selects the Onyx version. It defaults to latest. Change the S3_AWS_ACCESS_KEY_ID and S3_AWS_SECRET_ACCESS_KEY pair before you use the deployment in production. See the configuration reference for all settings.
4

Launch Onyx

To pull images from Docker Hub and start Onyx:
To build images from source instead:
If you first launched Onyx with the old onyx-stack project name, add -p onyx-stack to your command so Compose reuses your volumes.For example: docker compose -p onyx-stack up -d.
After the containers start, Onyx initializes its database and search index. Then open localhost:3000.

​
Onyx Lite

Onyx Lite runs the core chat experience with only PostgreSQL. It starts no OpenSearch, Redis, model servers, object store, or background workers. Connectors and search over indexed documents are disabled. Chat, user file uploads, Projects, Agent knowledge, and the code interpreter still work. Add the Lite overlay to the launch command:
The overlay moves the removed services to Compose profiles. For example, --profile opensearch brings OpenSearch back. The header of docker-compose.onyx-lite.yml lists the profiles.

​
Enabling Onyx Craft

Craft adds isolated sandbox containers and an egress proxy to the Docker Compose deployment. Craft requires a Business or Enterprise license and does not run on Onyx Lite. Use the Craft Docker Compose guide for both new and existing installations.

Deploy Craft on Docker Compose

Install the Craft overlay, set the Onyx URL, plan host capacity, and verify the runtime.

​
Next Steps

Configure Authentication

Set up authentication for your Onyx deployment with OAuth, OIDC, or SAML.

More Onyx Configuration Options

Learn about all available configuration options for your Onyx deployment.