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

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, 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, 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.

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.

Configuration and Multitenancy

All behavior is driven by environment variables centralized in 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.

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.

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:

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

4. Install dependencies:

   uv sync --all-extras

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

   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:

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 using the project's helper function:

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

Test the endpoint locally:

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

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

Write a unit test in backend/tests/unit/server/test_ping.py:

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.
• 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, and all API routes must follow the router registration pattern established in 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 and the inline code documentation in backend/onyx/main.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}