Skip to content

Kneo Agent Dashboard examples

Runnable deployment examples for kneo-dash — the Dashboard is a deployable service (FastAPI BFF + built SPA), so its examples are ways to run it against a Kneo Agent Platform, not agent specs. Use them to try the dashboard in a couple of minutes, or as starting points for a real deployment.

For the annotated walkthrough — first-run steps, auth modes, the state store — see docs/user/quickstart.md and docs/user/connecting.md, which are canonical; the matrix below is a quick index. When the two differ, the user docs win.

Scenario → example matrix

Scenario Example
Try it in ~2 min (Dashboard + ephemeral in-memory kneo-serv, static-dev admin) docker-compose.yml
Production shape — supported single-instance SQLite (OIDC + same-origin TLS proxy, external kneo-serv) docker-compose.prod.yml + nginx.conf
Production shape — best-effort multi-replica Postgres overlay (not soak-certified, per ADR-012) docker-compose.prod-postgres.yml + Dockerfile.postgres
All configuration knobs, annotated .env.example
Container-free (bundled-SPA wheel, ADR-011) see Container-free below

Reading order

  1. docker-compose.yml — the evaluation stack. docker compose up, open http://localhost:8090. Brings up an ephemeral in-memory kneo-serv and the Dashboard wired to it, in static-dev auth: one unauthenticated admin operator, no login. The simplest end-to-end look. Dev-only — the app refuses to boot in static mode without KNEO_DASH_DEV_MODE=1 (ADR-009 §5).
  2. .env.example — every setting the BFF reads, annotated: the platform connection (KNEO_URL/KNEO_API_KEY or a KNEO_PROFILE), OIDC, the session_secret, the state-store URL, and the optional Grafana/CORS knobs. Copy to .env and fill in real values.
  3. docker-compose.prod.yml + nginx.conf — the production shape: real OIDC (Authorization Code + PKCE, server-side RBAC), the supported single-instance SQLite dashboard state store, behind a same-origin TLS reverse proxy, pointed at an external kneo-serv you already operate. (Multi-replica Postgres is the separate best-effort overlay — docker-compose.prod-postgres.yml, ADR-012.) Serving the SPA and /api under one origin is what keeps the SameSite=Lax session cookie + the same-origin mutation guard working without CORS.

Container-free (no Docker)

The published wheel bundles the built SPA (ADR-011), so a bare install serves the full UI and API same-origin:

pip install kneo-dash==0.8.0
export KNEO_URL="https://kneo-serv.internal" KNEO_API_KEY="…"
export KNEO_DASH_AUTH_MODE=oidc KNEO_DASH_SESSION_SECRET="$(python -c 'import secrets;print(secrets.token_urlsafe(48))')"
# … the OIDC vars from .env.example …
kneo-dash                     # serves UI + /api on 127.0.0.1:8090

For dev/eval, KNEO_DASH_AUTH_MODE=static KNEO_DASH_DEV_MODE=1 skips OIDC.

Caveats

  • Static mode is dev/eval only — a single unauthenticated admin. Any real deployment must use KNEO_DASH_AUTH_MODE=oidc with a strong KNEO_DASH_SESSION_SECRET.
  • Placeholders are not secrets — every change-me / dev-admin-key / dash.example.com is a placeholder; retarget them (and your IdP client, TLS certs, and KNEO_URL) before any real use.
  • Single-instance for now — the prod example runs one replica. Multi-replica (shared session_secret, rolling migrations, secret rotation, backup/restore) is best-effort, not yet mature — tracked in ADR-012.
  • Image tags — kneo-dash:0.8.0 is pinned to the current release; the Dashboard is compatible with kneo-serv >=1.2.0,<2. Pin both in production.

Subsections

Files