Setup guide
Run your first comparison.
Umbono starts in deterministic demo mode. Live provider access is an optional server-side configuration.
Quick start
Use Node.js 20.9 or newer. The setup command creates a local environment file only when one does not already exist.
git clone https://github.com/Schramm2/umbono-dashboard.git
cd umbono-dashboard
npm ci
npm run setup
npm run devOpen http://localhost:3000, then choose Open studio. Demo mode needs no API key and makes no provider request.
Enable live comparisons
Edit .env.local and configure one OpenAI-compatible endpoint. Model IDs must match the IDs accepted by that endpoint.
UMBONO_API_KEY=your-server-side-key
UMBONO_BASE_URL=https://your-provider.example/v1
UMBONO_MODELS=your-model-id,another-model-idRestart the development server. The studio header will show Live provider ready, and the Live mode control will become available.
Never prefix the key with NEXT_PUBLIC_. Umbono sends prompts through /api/compare, so credentials are not included in browser JavaScript.
Environment variables
| Variable | Required | Purpose |
|---|---|---|
UMBONO_API_KEY | Live only | Bearer token sent to the configured provider. |
UMBONO_BASE_URL | No | API root. Defaults to the OpenAI API root. |
UMBONO_MODELS | Live only | Comma-separated allowlist shown in the studio. |
UMBONO_ALLOW_LIVE_IN_PRODUCTION | Production live only | Explicit opt-in after adding authentication and rate limiting. |
UMBONO_MAX_TOKENS | No | Output cap per model. Defaults to 800. |
UMBONO_REQUEST_TIMEOUT_MS | No | Per-model timeout. Defaults to 45,000 ms. |
UMBONO_MODEL_PRICING | No | JSON rates used for estimated USD cost. |
Build and deploy
Run the complete local quality gate before deployment:
npm run verify
npm run build
npm startDeploy as a Next.js application when live mode is needed. Set the same environment variables in your host and keep all credentials server-only. Production stays demo-only unless UMBONO_ALLOW_LIVE_IN_PRODUCTION=true; enable it only behind authentication and rate limiting.