Docker

Deploy Onyx with Docker Compose

Check out the Resourcing Guide before getting started with Docker.

Guide

Note: On Windows, the commands will be slightly different but all the steps are the same.

1. Install Requirements

   • Git
   • Docker (with compose)
2. Clone the Onyx repo

   git clone --depth 1 https://github.com/onyx-dot-app/onyx.git
   
3. Navigate to the compose files

   cd onyx/deployment/docker_compose
   
4. Launch Onyx

   To pull images from Docker Hub and start Onyx:

   docker compose up -d
   

   Alternatively, to build images from source:

   docker compose up -d --build --force-recreate
   

   If you’ve previously launched Onyx with the old onyx-stack service name, you’ll need to add -p onyx-stack to your launch command.

   For example: docker compose up -p onyx-stack -d.

After the containers come up, the system needs to go through an initialization process after which you can access Onyx at localhost:3000.

Enabling Onyx Craft

To enable Onyx Craft, use the installation script with the --include-craft flag:

cd onyx/deployment/docker_compose
./install.sh --include-craft

Then start the generated deployment:

cd onyx_data/deployment
docker compose up -d

The install script adds the Craft compose overlay, enables ENABLE_CRAFT=true, creates the sandbox bridge network, and configures the sandbox proxy.

Docker Compose Craft uses the Docker sandbox backend. The API server, background worker, and sandbox proxy need access to the host Docker socket to provision and manage sandbox containers. Treat this as root-equivalent access to the host.

For existing deployments, enabling Craft is more than setting ENABLE_CRAFT=true. You must also run the Craft compose overlay and set a SANDBOX_API_SERVER_URL that sandbox containers can reach.

Read the Craft deployment guide before enabling Craft on an existing Docker Compose deployment.

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.