Skip to content

Quickstart

Run the Kneo Agent Dashboard against a Kneo Agent Platform (kneo-serv) in ~10 minutes. The Dashboard is one deploy unit — a FastAPI BFF; the container image also bundles and serves the built SPA (the browser UI). It talks to the platform through kneo-client over /v1.

Prerequisites

  • A reachable kneo-serv endpoint (its URL) and an API key for it.
  • Python 3.12+ or Docker (for the container image).

Run it

Authentication — trial vs. production

KNEO_DASH_DEV_MODE=1 runs the Dashboard as a single, unauthenticated operator (static mode, admin role) — fine for a local trial on a trusted machine, and the Dashboard refuses to start in static mode without it so a real deploy can't silently be unauthenticated-admin (ADR-009 §5). For any shared or production deployment, drop KNEO_DASH_DEV_MODE and configure OIDC instead (KNEO_DASH_AUTH_MODE=oidc + KNEO_DASH_SESSION_SECRET + the OIDC provider settings — see connecting and the deployment/release setup).

docker run --rm -p 8090:8090 \
  -e KNEO_URL="https://kneo-serv.internal" \
  -e KNEO_API_KEY="…" \
  -e KNEO_DASH_DEV_MODE=1 \
  -v kneo-dash-state:/var/lib/kneo-dash \
  ghcr.io/kneo-agent/kneo-dash:latest

The image bundles the BFF and the built SPA (served by the BFF), so there's no separate frontend to deploy. The state store (annotations, saved filters, launch history) defaults to a SQLite file under /var/lib/kneo-dash — mount a volume there (as above) so it survives container restarts, or point KNEO_DASH_DB_URL at Postgres.

pip install kneo-dash
export KNEO_URL="https://kneo-serv.internal" KNEO_API_KEY="…"
export KNEO_DASH_DEV_MODE=1
kneo-dash   # serves the full app (UI + API) on http://127.0.0.1:8090

The published wheel bundles the browser UI (ADR-011) — the BFF serves it same-origin, so pip install gives the full dashboard without Docker, identical to the container. (Building the wheel from source needs Node to build the SPA; the published wheel already includes it. A pip install -e . dev checkout that hasn't built the SPA runs API-only — /api/* with no UI.)

Open http://localhost:8090 — you land on the Overview, the operator's at-a-glance answer to what's running · what needs attention · is production healthy.

The Overview page you land on — a top summary row (Running, Blocked, Failed, Pending human tasks, Total runs) with an error-rate and 7-day spend line, the environment switcher and operator chip in the header, and the Operate / Admin navigation down the left.

Your first five minutes

  1. Overview — scan the tiles (running · blocked · failed · pending human tasks) and the error-rate / spend lines. A non-zero failed or blocked tile is your cue.
  2. Runs — click the failed tile (or open Runs and set errors-only). Open a run.
  3. Trace — on a live run, flip Live tail to watch events stream (SSE); on a finished one, read the waterfall + Checkpoints to see where it went.
  4. Human tasks — if something's blocked, it's waiting on a person; decide it there (Human-in-the-loop).
  5. Launch (admin) — try Load → Deploy → Run on a spec to start a run end-to-end.

If a step misbehaves (empty env switcher, a 403, no live trace), the troubleshooting guide has a symptom index.

Configuration

Env var What
KNEO_URL + KNEO_API_KEY The platform endpoint + key (or a kneo-client profile / ~/.config/kneo/client.toml). See Connecting.
KNEO_DASH_DB_URL Dashboard-local state store (annotations, saved filters). Unset → a local SQLite file (the container defaults it to /var/lib/kneo-dash/state.db on a volume); postgresql://… for multi-replica/HA (needs the postgres extra).
KNEO_DASH_GRAFANA_URL Optional Grafana base URL for the Overview deep-link (real time-series live in Grafana).
KNEO_DASH_CORS_ORIGINS Dev only (the Vite proxy). The shipped image is same-origin (BFF serves the SPA), which is the only supported model once auth lands — credentialed cross-origin hosting is out of scope (ADR-009).

Security posture (read before exposing it)

Run OIDC mode for any real deployment

Set KNEO_DASH_AUTH_MODE=oidc (with a strong KNEO_DASH_SESSION_SECRET and your provider config) so operators authenticate and the BFF enforces the required capability server-side on every privileged action (the role resolves through the reassignable Access map) — the platform credential is a shared per-env service account, so the BFF is the real per-operator gate. The default static mode is unauthenticated and dev-only: the app refuses to start in it unless you also set KNEO_DASH_DEV_MODE=1. The SPA is served same-origin with an HttpOnly/Secure session cookie; a trusted-network / reverse-proxy layer is now optional defence-in-depth, not a prerequisite. See ADR-009.

Where next