Installation & Start

There are two ways to run Orinth: the packaged macOS app, or the source checkout. They run the same backend and frontend — the app is a supervisor around the same two servers, so there is no second implementation to keep in sync.

Option A — the macOS app

Download the .dmg, drag Orinth.app to /Applications, and double-click. No terminal, no make.

The bundle is universal — one file for both Apple silicon and Intel Macs.

Because the .dmg ships source rather than bundled runtimes, first launch downloads and installs the ML environment (roughly 2.7 GB, 10–20 minutes, needs a network connection) with per-step progress on screen. Later launches start in seconds.

The build is ad-hoc signed but not notarized, so the first launch on a machine that did not build it needs one manual Gatekeeper approval: right-click the app, choose Open, then confirm.

Everything the app generates lives under ~/Library/Application Support/, never in a repo checkout.

Option B — from source

Prerequisites

• Python 3.11 and uv
• Node and pnpm
• make

Quickstart

git clone https://github.com/L007/orinth.git
cd orinth

# 1. copy the environment templates
cp .env.example .env
cp frontend/.env.example frontend/.env.local

# 2. verify prerequisites
make doctor

# 3. start backend :8000 and frontend :3000 together
make dev

make dev starts both servers with interleaved logs in one terminal. It fails fast if port 8000 or 3000 is already in use, and Ctrl-C cleanly stops both processes.

The API docs are served at http://localhost:8000/docs; the app at http://localhost:3000.

Running the servers separately

# backend
cd backend
uv venv --python 3.11
source .venv/bin/activate
uv sync
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# frontend
cd frontend
pnpm install
pnpm dev

Environment variables

Backend settings live in the root .env:

Variable	Purpose
MODELS_DIR, DATASETS_DIR, STORAGE_DIR	Local paths for reference assets and generated runtime artifacts.
DATABASE_URL	SQLite connection string.
BACKEND_CORS_ORIGINS	Origins allowed to call the API directly. Defaults to http://localhost:3000.
HUGGINGFACE_HUB_TOKEN (alias HF_TOKEN)	Only needed for private or gated Hugging Face models.

Frontend settings live in frontend/.env.local:

Variable	Purpose
BACKEND_PROXY_ORIGIN	Where the dev server proxies /api/* and /media/*. Defaults to http://127.0.0.1:8000.
NEXT_PUBLIC_BACKEND_URL	Leave unset for the normal local setup. Set it only when deliberately exposing the backend at a separate public URL.

Quality gates

Before committing, run every documented gate in one shot:

make check

check runs backend lint (ruff) and the fast backend test suite, then frontend typecheck, lint, and build, stopping at the first failure. The individual targets — make lint-backend, make test, make typecheck, make lint, make build — are available on their own.

Building the desktop app

make desktop

The output is a universal .dmg under desktop/src-tauri/target/universal-apple-darwin/release/bundle/dmg/.