# How to Set Up a Development Environment for Onyx: Complete Local Developer Guide

> Set up your Onyx development environment quickly. Follow this guide to install Python, Node, and Docker dependencies. Start the model server, backend, and frontend efficiently.

- Repository: [Onyx/onyx](https://github.com/onyx-dot-app/onyx)
- Tags: how-to-guide
- Published: 2026-03-28

---

**To set up a development environment for Onyx, run Postgres, Vespa, Redis, and MinIO in Docker, install Python 3.11 and Node 22 dependencies, then start the model server on port 9000, background Celery workers, the FastAPI backend on port 8080, and the Next.js frontend on port 3000.**

Onyx is a full-stack Gen-AI and enterprise search platform maintained by `onyx-dot-app/onyx` that consists of a Python FastAPI backend, a Next.js frontend, a standalone model server, and background job workers. Developing locally requires orchestrating four distinct runtime processes alongside external data stores. This guide follows the exact implementation details found in [`contributing_guides/dev_setup.md`](https://github.com/onyx-dot-app/onyx/blob/main/contributing_guides/dev_setup.md) and [`AGENTS.md`](https://github.com/onyx-dot-app/onyx/blob/main/AGENTS.md) to ensure your local environment matches production architecture.

## Prerequisites and Architecture

Before installing dependencies, ensure your system meets the base requirements. Onyx requires **Python 3.11** for the backend and **Node 22.20.0** for the frontend. You will also need **Docker** to host external services and **uv** for Python package management.

The development architecture involves four concurrent processes you must start manually:

1. **Web UI** – Next.js development server on `http://localhost:3000`
2. **Backend API** – FastAPI application in [`backend/onyx/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/main.py) on port 8080
3. **Model Server** – Embedding and LLM inference service in [`backend/model_server/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/model_server/main.py) on port 9000
4. **Background Workers** – Celery workers managed by [`backend/scripts/dev_run_background_jobs.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/scripts/dev_run_background_jobs.py) that handle connector syncing, indexing, and document pruning

These services depend on Docker containers running Postgres, Vespa, Redis, and MinIO.

## Step 1 — Launch External Services with Docker

Start the required infrastructure containers before running any application code. According to [`deployment/docker_compose/docker-compose.yml`](https://github.com/onyx-dot-app/onyx/blob/main/deployment/docker_compose/docker-compose.yml) and [`docker-compose.dev.yml`](https://github.com/onyx-dot-app/onyx/blob/main/docker-compose.dev.yml), you need the `index` (Vespa), `relational_db` (Postgres), `cache` (Redis), and `minio` services.

Run the following command from the repository root:

```bash
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d index relational_db cache minio

```

This command detaches the containers to run in the background, providing the data persistence and vector search capabilities required by the Onyx backend.

## Step 2 — Configure the Python Backend Environment

Onyx uses **uv** for fast Python dependency management. Create a virtual environment pinned to Python 3.11 and install all backend packages including development extras.

Create and activate the virtual environment:

```bash
uv venv .venv --python 3.11
source .venv/bin/activate

```

On Windows PowerShell, use `.venv\Scripts\Activate.ps1` instead.

Install dependencies declared in [`backend/pyproject.toml`](https://github.com/onyx-dot-app/onyx/blob/main/backend/pyproject.toml):

```bash
uv sync --all-extras

```

Install Playwright binaries required for the Web connector:

```bash
uv run playwright install

```

Initialize the database schema using Alembic migrations stored in `backend/alembic/versions/`:

```bash
cd backend
alembic upgrade head

```

## Step 3 — Configure the Node.js Frontend

The frontend requires Node 22.20.0 as specified in [`web/package.json`](https://github.com/onyx-dot-app/onyx/blob/main/web/package.json). Use **nvm** to install and switch to the correct version:

```bash
nvm install 22 && nvm use 22
node -v

```

Install frontend dependencies:

```bash
cd web
npm i

```

## Step 4 — Start the Four Development Processes

With dependencies installed and Docker services running, start each Onyx component in a separate terminal window. The startup order matters: begin with the model server, then background workers, then the backend API, and finally the frontend.

**Terminal 1 — Model Server:**

```bash
cd backend
uvicorn model_server.main:app --reload --port 9000

```

**Terminal 2 — Background Workers:**

```bash
cd backend
python ./scripts/dev_run_background_jobs.py

```

**Terminal 3 — Backend API:**

```bash
cd backend
AUTH_TYPE=basic uvicorn onyx.main:app --reload --port 8080

```

Setting `AUTH_TYPE=basic` enables simple authentication for local development as implemented in [`backend/onyx/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/main.py).

**Terminal 4 — Frontend:**

```bash
cd web
npm run dev

```

Once all four processes display ready states, open `http://localhost:3000` to access the Onyx onboarding wizard.

## Step 5 — Configure Code Quality Tools

Enable pre-commit hooks to enforce formatting and linting rules defined in [`.pre-commit-config.yaml`](https://github.com/onyx-dot-app/onyx/blob/main/.pre-commit-config.yaml):

```bash
uv run pre-commit install

```

This ensures your contributions match the repository's style guidelines before submission.

## Summary

- **Docker services** – Run Postgres, Vespa, Redis, and MinIO via [`docker-compose.yml`](https://github.com/onyx-dot-app/onyx/blob/main/docker-compose.yml) and [`docker-compose.dev.yml`](https://github.com/onyx-dot-app/onyx/blob/main/docker-compose.dev.yml) before starting application code
- **Python setup** – Use `uv` with Python 3.11, run `uv sync --all-extras`, install Playwright, and execute `alembic upgrade head` from the `backend/` directory
- **Node setup** – Install Node 22.20.0 via nvm and run `npm i` in the `web/` directory
- **Runtime processes** – Start four separate services: model server on port 9000, background workers via [`dev_run_background_jobs.py`](https://github.com/onyx-dot-app/onyx/blob/main/dev_run_background_jobs.py), backend API on port 8080 with `AUTH_TYPE=basic`, and frontend on port 3000
- **Key files** – Reference [`contributing_guides/dev_setup.md`](https://github.com/onyx-dot-app/onyx/blob/main/contributing_guides/dev_setup.md), [`backend/pyproject.toml`](https://github.com/onyx-dot-app/onyx/blob/main/backend/pyproject.toml), [`backend/onyx/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/main.py), and [`AGENTS.md`](https://github.com/onyx-dot-app/onyx/blob/main/AGENTS.md) for architecture details

## Frequently Asked Questions

### What are the background workers used for in Onyx development?

The background workers are Celery processes started via [`backend/scripts/dev_run_background_jobs.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/scripts/dev_run_background_jobs.py) that handle asynchronous tasks including document indexing, connector synchronization, permission pruning, and embedding generation. Without these running, document uploads and connector crawls will queue indefinitely without processing.

### Can I use a different Python version than 3.11?

No. The [`backend/pyproject.toml`](https://github.com/onyx-dot-app/onyx/blob/main/backend/pyproject.toml) explicitly requires Python 3.11, and dependencies are locked to this version. Using Python 3.12 or 3.10 will cause resolution failures during `uv sync` or runtime incompatibilities with the FastAPI application defined in [`backend/onyx/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/main.py).

### Is Docker mandatory for local development?

Yes. The application requires Postgres for relational data, Vespa for vector search, Redis for caching, and MinIO for object storage. These services are defined in [`deployment/docker_compose/docker-compose.yml`](https://github.com/onyx-dot-app/onyx/blob/main/deployment/docker_compose/docker-compose.yml) and are not optional for a functional development environment, as the backend code in [`onyx/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/onyx/main.py) expects these connections on startup.

### How do I debug the backend with VS Code?

The repository includes a pre-configured VS Code launch configuration in [`.vscode/launch.json`](https://github.com/onyx-dot-app/onyx/blob/main/.vscode/launch.json) that spawns the model server, background workers, and backend API with attached debuggers. Alternatively, run `uvicorn onyx.main:app --reload` with the VS Code Python debugger attached to port 8080, ensuring `AUTH_TYPE=basic` is set in your environment variables for authentication bypass.