Quickstart

Run Samaritan locally

Prerequisites

• Python 3.11+
• Node.js 20+
• npm 10+
• uv
• .env with provider keys (minimum: OPENAI_API_KEY)

1) Clone

git clone https://github.com/scaleborg/samaritan.git
cd samaritan
cp .env.example .env

2) Install Backend Dependencies

uv venv .venv
source .venv/bin/activate
make install

3) Install Frontend Dependencies

cd frontend
npm install
cd ..

4) Run

Recommended:

source .venv/bin/activate
make dev

Split terminals:

# terminal 1
source .venv/bin/activate
make dev-backend

# terminal 2
make dev-frontend

5) Verify

• Frontend: http://localhost:5174
• OpenAPI: http://localhost:8000/docs
• Health check: curl http://localhost:8000/health

Operator Key Model

Samaritan currently uses operator-managed provider keys via backend environment configuration. This is operator BYOK, not end-user key entry in UI.