- Go 76.8%
- CSS 12.1%
- templ 10.2%
- Dockerfile 0.5%
- Nix 0.4%
|
All checks were successful
Docker release / release (push) Successful in 14s
- cost by type: segments grow left to right on entry, ranked rows with share bars fade in; hovering a segment or row highlights its counterpart and shows a tooltip (CSS only via :has); more spacing between bar and list - heatmap: calendar-sized month cells with day numbers and a statistics panel (total, daily average, active days, busiest day/month, cost per request, forecast); annual cells scale with the card width - entry staggering via a --i index instead of fixed nth-child delays |
||
|---|---|---|
| .forgejo/workflows | ||
| cmd/cortecs-dashboard | ||
| internal | ||
| web | ||
| .dockerignore | ||
| .env.example | ||
| .gitignore | ||
| AGENTS.md | ||
| docker-compose.yml | ||
| Dockerfile | ||
| flake.lock | ||
| flake.nix | ||
| go.mod | ||
| go.sum | ||
| README.md | ||
Cortecs Usage Dashboard
Web app that fetches the usage (cost, tokens, requests) of a cortecs.ai project via the Cortecs Management API and visualizes it as a dashboard. Self-hosted, prices in EUR.
Developed with GLM 5.3 Flash via cortecs.ai.
A single Go binary: server-side rendering with templ + HTMX, charts as server-rendered SVG, all assets embedded. No Node.js toolchain.
Features
- Balance with low-balance warning
- Cost, requests and token usage (incl. cache read/write ratio) per range (Today / 7 days / 30 days / Month / custom range)
- Cost chart (cumulative or per bucket), breakdown by model / provider / API key / user
- Monthly heatmap of daily costs (GitHub contribution graph style)
- Budget rules with consumed share, request logs of the last 24 h
- CSV export of the usage rows of the selected range
- Multi-project support (switcher in the header), auto-refresh every 60 s
- View state lives in the URL — every view is refresh-proof and shareable
Development
nix develop # Go + templ + gopls (alternatively: direnv allow)
cp .env.example .env.local # CORTECS_API_KEY=<management key>
templ generate # after changing *.templ files
go run ./cmd/cortecs-dashboard # http://localhost:3000 (loads .env.local)
go test ./...
Generated templ files (*_templ.go) are committed so that go build and the Docker build work without the templ CLI — run templ generate (or templ generate --watch) after editing .templ files.
Configuration
Everything is configured via environment variables — the project registry is server-side and env-only; keys never leave the server. For local development .env.local is loaded automatically (already-set variables take precedence; -env-file selects another file).
| Variable | Meaning |
|---|---|
CORTECS_API_KEY |
Management key of the default project (ID default) |
CORTECS_PROJECTS |
Comma-separated list of further project IDs (slugs: a-z, 0-9, hyphen) |
CORTECS_PROJECT_<ID>_KEY |
Management key per project (- → _, e.g. team-alpha → CORTECS_PROJECT_TEAM_ALPHA_KEY) |
CORTECS_PROJECT_<ID>_LABEL |
Optional display name per project (CORTECS_PROJECT_DEFAULT_LABEL for the default project) |
LOW_BALANCE_EUR |
Low-balance warning threshold in EUR (default 10, read at runtime; the old NEXT_PUBLIC_LOW_BALANCE_EUR is still accepted) |
ALERT_WEBHOOK_URL |
Optional: enables alerts — POSTs a plain-text notification (ntfy-compatible: Title/Tags/Priority headers) when the balance drops below LOW_BALANCE_EUR or a budget reaches ALERT_BUDGET_PERCENT; e.g. https://ntfy.sh/<secret-topic> |
ALERT_WEBHOOK_TOKEN |
Optional bearer token for the webhook (Authorization: Bearer …) |
ALERT_BUDGET_PERCENT |
Budget share that triggers an alert (default 90) |
ALERT_INTERVAL_MINUTES |
Check interval (default 15, minimum 1) |
METRICS_ENABLED |
true serves Prometheus metrics at /metrics (balance, cost/requests/tokens per day/week/month, budgets; behind Basic Auth when enabled) |
CACHE_TTL_SECONDS |
Lifetime of the in-memory API response cache in seconds (default 30, 0 disables it; the refresh button always bypasses it) |
TZ |
Time zone for displaying timestamps and computing ranges (Docker image default: Europe/Berlin) |
BASIC_AUTH_USERNAME + BASIC_AUTH_PASSWORD |
Optional: enables Basic Auth for the whole app (both required) |
PORT / LISTEN_ADDR |
Listen port (default 3000) or full address, e.g. 127.0.0.1:3000 |
CORTECS_BASE_URL |
Override the API base URL (default https://api.cortecs.ai/v1, useful for tests) |
Docker (production)
docker build -t cortecs-dashboard .
docker run -d --name cortecs-dashboard -p 3000:3000 \
--env-file .env.local \
cortecs-dashboard
Or with Compose (uses .env.local):
docker compose up -d --build
The Dockerfile is a multi-stage build: a static Go binary (CGO_ENABLED=0) on top of gcr.io/distroless/static-debian13:nonroot — no shell, non-root user, CA certificates and tzdata included. Port 3000, healthcheck via cortecs-dashboard -healthcheck against /api/health (no Cortecs call, no secrets — the route stays public even with Basic Auth). All configuration happens at runtime; no secrets in the image.
Release automation (Forgejo)
The Forgejo workflow .forgejo/workflows/release.yml builds and publishes the Docker image:
- Trigger: push of a
v*tag (e.g.git tag v0.2.0 && git push origin v0.2.0) or manually viaworkflow_dispatch. - Container registry: the image is pushed to the instance's container registry:
<instance>/<owner>/cortecs-dashboard:<tag>pluslatest. Runs on the runner labelubuntu-latest-thingy. - Forgejo release: for
v*tags a release with image reference and digest is created automatically (existing releases are not overwritten).
Authentication: by default the automatic workflow token (secrets.GITHUB_TOKEN). If the instance does not allow package pushes with it, store a Forgejo access token with write access to packages and releases as secret REGISTRY_TOKEN (plus REGISTRY_USER if the token owner differs).
Note: the image is built for the runner's architecture (single platform, no multi-arch).
Access protection
The dashboard and API routes expose cost and usage data — protect them when deploying:
- Basic Auth (built in): set
BASIC_AUTH_USERNAMEandBASIC_AUTH_PASSWORD. Dashboard and API routes are protected;/api/healthand static assets stay public (/api/healthonly returns{"status":"ok"}). - Reverse proxy: alternatively put Basic Auth/SSO in front of the container (Caddy, Traefik, nginx) and only expose it internally.
HTTP endpoints
| Route | Purpose |
|---|---|
GET / |
Dashboard (full page; HTMX requests get the #dashboard fragment) |
GET /api/health |
Liveness, no data |
GET /api/projects |
Configured projects (IDs/labels only) |
GET /api/balance, /api/usage, /api/budgets, /api/logs |
Read-only JSON proxy to the Cortecs API (?project=<id>, whitelisted params) |
GET /api/usage/export |
CSV export of the usage rows (same params as /api/usage) |
CSV export
"Export CSV" next to the range filter downloads the usage rows of the selected range (semicolon-separated, decimal comma, UTF-8 BOM — opens directly in Excel/LibreOffice with a German locale).
Security
- The management key is read server-side only, never rendered, logged or returned.
.env*is excluded via.gitignoreand.dockerignore.- Read-only management calls only (usage, balance, budgets, logs) — no write endpoints.