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

./rh worktree <name> shifts the backend, frontend, Postgres, Redis and Flower ports by 10 per worktree and gives it its own Postgres and Redis containers, so several checkouts can run at the same time. The offset is recorded in .rhesis-ports at the worktree root; ./rh dev status prints it. The mock servers, chatbot, Polyphemus and docs site keep the ports above — one instance serves every checkout.

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