Web App, die den Verbrauch (Kosten, Tokens, Requests) eines cortecs.ai-Projekts über die Cortecs Management API abruft und als Dashboard visualisiert.
  • Go 76.8%
  • CSS 12.1%
  • templ 10.2%
  • Dockerfile 0.5%
  • Nix 0.4%
Find a file
Philipp 8f8973c791
All checks were successful
Docker release / release (push) Successful in 14s
feat: animated cost-by-type card and heatmap statistics panel
- 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
2026-11-12 14:34:25 +01:00
.forgejo/workflows build: distroless Docker image and updated release workflow 2026-11-07 14:25:32 +01:00
cmd/cortecs-dashboard feat: webhook alerts for low balance and budgets 2026-11-12 13:28:45 +01:00
internal feat: animated cost-by-type card and heatmap statistics panel 2026-11-12 14:34:25 +01:00
web feat: animated cost-by-type card and heatmap statistics panel 2026-11-12 14:34:25 +01:00
.dockerignore build: distroless Docker image and updated release workflow 2026-11-07 14:25:32 +01:00
.env.example feat: webhook alerts for low balance and budgets 2026-11-12 13:28:45 +01:00
.gitignore feat!: port dashboard to Go with templ and HTMX 2026-11-07 14:25:32 +01:00
AGENTS.md feat: animated cost-by-type card and heatmap statistics panel 2026-11-12 14:34:25 +01:00
docker-compose.yml build: distroless Docker image and updated release workflow 2026-11-07 14:25:32 +01:00
Dockerfile build: distroless Docker image and updated release workflow 2026-11-07 14:25:32 +01:00
flake.lock chore: switch nix dev shell to Go and templ 2026-11-07 14:25:32 +01:00
flake.nix chore: build without cgo in the dev shell 2026-11-12 13:15:22 +01:00
go.mod feat!: port dashboard to Go with templ and HTMX 2026-11-07 14:25:32 +01:00
go.sum feat!: port dashboard to Go with templ and HTMX 2026-11-07 14:25:32 +01:00
README.md feat: webhook alerts for low balance and budgets 2026-11-12 13:28:45 +01:00

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 via workflow_dispatch.
  • Container registry: the image is pushed to the instance's container registry: <instance>/<owner>/cortecs-dashboard:<tag> plus latest. Runs on the runner label ubuntu-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:

  1. Basic Auth (built in): set BASIC_AUTH_USERNAME and BASIC_AUTH_PASSWORD. Dashboard and API routes are protected; /api/health and static assets stay public (/api/health only returns {"status":"ok"}).
  2. 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 .gitignore and .dockerignore.
  • Read-only management calls only (usage, balance, budgets, logs) — no write endpoints.