# How to Contribute to the Onyx Project: A Complete Developer's Guide

> Learn how to contribute to the Onyx project easily. Follow our step-by-step guide for developers to make your first Onyx contribution via fork and pull request.

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

---

**Yes, Onyx welcomes contributions from developers of all skill levels through its documented fork-and-pull-request workflow.**

Onyx is an open-source, community-driven AI platform that powers enterprise search and conversational AI. Whether you want to fix bugs, add connectors, improve documentation, or extend the API, you can contribute to the Onyx project by following the established development workflow and coding standards enforced throughout the codebase.

## Understanding the Onyx Architecture

Before diving into code changes, familiarize yourself with the repository structure. The codebase centers on a **FastAPI backend** that orchestrates dozens of feature-specific routers and a **Celery-based background system** for asynchronous document processing.

### FastAPI Backend and Router Registration

The application bootstrap happens in [`backend/onyx/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/main.py), where the `FastAPI` instance is created and routers are registered via `include_router_with_global_prefix_prepended`. Each major feature lives in its own router module within `backend/onyx/server/`.

For example, chat functionality resides in [`backend/onyx/server/query_and_chat/chat_backend.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/query_and_chat/chat_backend.py), while authentication and document handling have dedicated router files. The middleware stack—including latency logging, request-ID propagation, and CORS—is configured in [`backend/onyx/server/middleware/latency_logging.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/middleware/latency_logging.py).

### Celery Background Workers

Heavy tasks like document chunking, embedding generation, and vector database syncing run asynchronously through Celery workers. The system defines multiple worker types (`primary`, `docfetching`, `docprocessing`, `heavy`) orchestrated by the periodic poller logic in [`backend/onyx/background/periodic_poller.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/background/periodic_poller.py).

### Configuration and Multitenancy

All behavior is driven by environment variables centralized in [`backend/onyx/configs/app_configs.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/configs/app_configs.py). The optional multitenancy mode, which isolates data per tenant and integrates with the vector database, is initialized in [`backend/onyx/setup.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/setup.py).

## Setting Up Your Local Development Environment

To contribute to the Onyx project effectively, you must run the full service stack locally. The repository provides detailed instructions in [`contributing_guides/dev_setup.md`](https://github.com/onyx-dot-app/onyx/blob/main/contributing_guides/dev_setup.md).

1. **Fork and clone** the repository from `onyx-dot-app/onyx` on GitHub.
2. **Launch dependencies** using Docker Compose to spin up Postgres, Vespa, Redis, and MinIO.
3. **Create a virtual environment** with Python 3.11:

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

4. **Install dependencies**:

   ```bash
   uv sync --all-extras
   ```

5. **Install pre-commit hooks** to enforce code quality automatically:

   ```bash
   uv run pre-commit install
   ```

## Contribution Workflow and Code Standards

Onyx enforces strict code quality through automated tooling. Every commit triggers **pre-commit hooks** that run formatting, import ordering, and `mypy` static type checking. The project requires all code to pass the full test suite before merging.

When preparing your contribution:

- **Run tests locally** using `uv run pytest` to execute unit, integration, and end-to-end tests.
- **Follow type hints** extensively—the codebase uses strict typing throughout.
- **Reference existing patterns** in `backend/onyx/server/` when adding new functionality.

Submit your changes via a pull request that references an open issue (or create a new issue describing the problem or feature). Ensure CI passes all checks before requesting review.

## Example: Adding a New API Endpoint

Here is a practical example of contributing a simple health-check endpoint, demonstrating the router registration pattern used throughout Onyx.

Create the router file at [`backend/onyx/server/ping.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/ping.py):

```python
from fastapi import APIRouter

router = APIRouter()

@router.get("/ping")
def ping() -> dict[str, str]:
    """Health-check endpoint used by CI and external monitors."""
    return {"status": "ok"}

```

Register the router in [`backend/onyx/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/main.py) using the project's helper function:

```python
from onyx.server.ping import router as ping_router
include_router_with_global_prefix_prepended(application, ping_router)

```

Test the endpoint locally:

```bash
curl -X GET http://localhost:8080/api/ping

# Expected response: {"status":"ok"}

```

Write a unit test in [`backend/tests/unit/server/test_ping.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/tests/unit/server/test_ping.py):

```python
from fastapi.testclient import TestClient
from onyx.main import get_application

def test_ping():
    client = TestClient(get_application())
    response = client.get("/api/ping")
    assert response.status_code == 200
    assert response.json() == {"status": "ok"}

```

Run the specific test with `uv run pytest backend/tests/unit/server/test_ping.py`.

## Summary

- **Onyx is fully open-source** and accepts contributions via GitHub pull requests following the fork-and-PR model documented in [`CONTRIBUTING.md`](https://github.com/onyx-dot-app/onyx/blob/main/CONTRIBUTING.md).
- **Local development requires Docker Compose** for dependencies (Postgres, Vespa, Redis, MinIO) and `uv` for Python environment management.
- **Code quality is automated** through pre-commit hooks, `mypy` type checking, and a comprehensive pytest suite.
- **The architecture separates concerns** between FastAPI routers for synchronous requests and Celery workers for background document processing.
- **New contributors should start** with the development setup guide, then explore `backend/onyx/server/` for implementation patterns.

## Frequently Asked Questions

### What programming languages and frameworks does Onyx use?

Onyx is built primarily in **Python** using **FastAPI** for the REST API backend and **Celery** for asynchronous task processing. The frontend uses modern JavaScript/TypeScript frameworks, while the vector database layer integrates with Vespa. All Python code requires strict type hints enforced by `mypy`.

### How do I run the test suite before submitting a contribution?

Execute the full test suite using `uv run pytest` from the repository root. This runs unit tests, integration tests, and end-to-end tests against your local Docker Compose stack. Individual test files can be targeted directly, such as `uv run pytest backend/tests/unit/server/test_ping.py` for specific functionality.

### What code quality standards does the Onyx project enforce?

The project enforces formatting, import ordering, and static type checking through **pre-commit hooks** that run automatically on every commit. Configuration is managed via environment variables in [`backend/onyx/configs/app_configs.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/configs/app_configs.py), and all API routes must follow the router registration pattern established in [`backend/onyx/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/main.py).

### Where can I get help with my contribution or discuss ideas?

Onyx maintains an active **Discord community** for real-time help with development setup and debugging. The repository also includes a **roadmap** showing upcoming features and priorities. For technical questions specific to implementation details, refer to [`contributing_guides/dev_setup.md`](https://github.com/onyx-dot-app/onyx/blob/main/contributing_guides/dev_setup.md) and the inline code documentation in [`backend/onyx/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/main.py).