Skip to Content
ContributeDevelopment Setup

Development setup

Two paths: local dev (./rh dev …) for day-to-day work, or all-in-one Docker (./rh start) for a full environment without local service wiring.

Prerequisites

uv  for Python tooling, Node.js 18+ for the frontend and docs, and Docker for ./rh dev up and ./rh start.

Default ports

WhatPort
Backend API / OpenAPI (./rh dev backend)8080
Frontend / Next.js (./rh dev frontend)3000
Documentation site (./rh dev docs)3001
Dev PostgreSQL (./rh dev up)11000
Dev Redis (./rh dev up)11001
Mock LLM server (./rh dev mock-llm)18080
Mock Chatbot server (./rh dev mock-chatbot)18090

Clone the repo

Terminal
git clone https://github.com/YOUR_USERNAME/rhesis.git
cd rhesis
git remote add upstream https://github.com/rhesis-ai/rhesis.git

From the repo root:

Terminal
./rh dev init         # env files (one-time)
./rh dev up             # postgres and redis
./rh dev backend        # http://localhost:8080 (API docs at /docs)
./rh dev worker         # Celery worker for background tasks
./rh dev frontend       # http://localhost:3000

./rh dev init writes apps/backend/.env and apps/frontend/.env.local. If those files already exist and were not created by init, the script may prompt before overwriting.

Tip: ./rh dev tmux starts all of the above in one tmux session, one window per service. Run ./rh help or ./rh dev for the full command list (./rh dev docs, ./rh dev status, etc.).

Optionally, start the mock servers (see LLM access):

Terminal
./rh dev mock-llm      # http://localhost:18080
./rh dev mock-chatbot  # http://localhost:18090

LLM access

Rhesis relies on LLMs for test generation and evaluation. Three options:

  1. Use the LLM provided by Rhesis.ai (recommended) — create an account at app.rhesis.ai , generate an API key, and paste it into apps/backend/.env:
apps/backend/.env
RHESIS_API_KEY=your_api_key
  1. Bring your own LLM — add your model under Model → Add → Language Model, and set it as the default for generation, evaluation, and execution.
  2. Use the mock LLM — single-turn only, still in development and may be buggy. Start it with ./rh dev mock-llm and ./rh dev mock-chatbot.

Path 2: Full stack with Docker

Terminal
./rh start              # pull prebuilt images (GHCR), then up
./rh start --build        # optional: build images from local Dockerfiles

Frontend at http://localhost:3000 , API at http://localhost:8080/docs . Manage the stack with ./rh logs, ./rh stop, ./rh restart (add --build to rebuild), and ./rh delete. This mode is aimed at local testing, including convenient sign-in behavior. For production deployment, see the deployment documentation.

Branching, commits, and checks

  • Feature branches and Conventional Commits 
  • uvx pre-commit install before your first commit
  • Run make format, make lint, and make test from apps/backend/, sdk/, or apps/frontend/ as appropriate

Troubleshooting

  • ./rh dev up fails: ensure Docker is running and nothing else is bound to the dev Postgres/Redis ports above
  • Backend database errors: run ./rh dev up after ./rh dev init; for non-local databases, see Environment config
  • Stale Python env: from apps/backend, run uv sync again and use apps/backend/.venv
  • Still stuck? Ask on Discord 
OverviewCoding Standards