Environment-variable reference¶
Every setting the Kneo Agent Dashboard BFF reads, grouped by concern. Dashboard-server
settings use the KNEO_DASH_ prefix (e.g. KNEO_DASH_AUTH_MODE); the platform
connection it proxies uses the kneo-client KNEO_ variables (no DASH). Unset
values fall back to the defaults shown.
The dashboard is a thin BFF over a Kneo Agent Platform — it holds no platform truth. These variables configure the BFF process and its own state store; the platform's own configuration is documented with kneo-serv.
Compose deployments (0.8.0): the supported production recipes forward every production-relevant
KNEO_DASH_*from your.env(--env-fileonly interpolates — an unforwarded variable would silently never reach the container). Four are deliberately not forwarded as dev-only:KNEO_DASH_DEV_MODE,KNEO_DASH_STATIC_OPERATOR_ROLE,KNEO_DASH_SPA_DIR(baked into the image), andKNEO_DASH_CORS_ORIGINS(same-origin production keeps it empty). A CI parity guard holds the recipes to this. An empty value behaves exactly like an unset one.
Deployment / serving¶
| Variable | Default | Meaning |
|---|---|---|
KNEO_DASH_SPA_DIR |
(unset) | Directory of the built SPA to serve. The shipped container sets this (/app/static) so the BFF serves the dashboard itself (ADR-008). Leave unset in dev — the Vite dev server serves the SPA and proxies /api. |
KNEO_DASH_DEFAULT_PROFILE |
(unset) | kneo-client profile to bind for the platform connection. Unset → the client's default resolution (KNEO_PROFILE / KNEO_URL + KNEO_API_KEY / config file). See Platform connection. |
Authentication¶
static mode is a single, unauthenticated "static operator" for local development only —
the app refuses to start in static mode unless KNEO_DASH_DEV_MODE is set (ADR-009 §5),
so a production deploy can never silently run as unauthenticated admin. Production uses oidc.
| Variable | Default | Meaning |
|---|---|---|
KNEO_DASH_AUTH_MODE |
static |
static (dev-only) or oidc (production: session cookie + OIDC login). |
KNEO_DASH_DEV_MODE |
false |
Explicit dev-context opt-in. Required for static mode to boot; never set in production. |
KNEO_DASH_STATIC_OPERATOR_ROLE |
admin |
The static operator's role (viewer | operator | admin). Ignored in oidc mode (the role comes from the identity's claims). |
OIDC provider¶
Used only when KNEO_DASH_AUTH_MODE=oidc. Discovery is {issuer}/.well-known/openid-configuration.
| Variable | Default | Meaning |
|---|---|---|
KNEO_DASH_OIDC_ISSUER |
(unset) | Issuer base URL. |
KNEO_DASH_OIDC_CLIENT_ID |
(unset) | Registered client id. |
KNEO_DASH_OIDC_CLIENT_SECRET |
(unset) | Client secret. |
KNEO_DASH_OIDC_REDIRECT_URL |
(unset) | Registered callback URL — must match the provider, e.g. https://dash.example/api/callback. |
KNEO_DASH_OIDC_SCOPES |
openid email profile |
Requested scopes. |
KNEO_DASH_OIDC_ROLE_CLAIM |
roles |
The ID-token/userinfo claim holding the operator's group/role values. |
KNEO_DASH_OIDC_ROLE_MAP |
{} |
JSON map of claim-value → dashboard role (viewer|operator|admin), e.g. {"kneo-admins":"admin","kneo-ops":"operator"}. Default-deny: an identity with no mapped role is refused (ADR-009 §5). |
KNEO_DASH_OIDC_BOOTSTRAP_ADMIN |
(unset) | A sub or email always granted admin — an explicit, auditable lockout-recovery entry (not a standing backdoor). |
KNEO_DASH_POST_LOGIN_REDIRECT |
/ |
Where the SPA lands after a successful login. |
Sessions¶
Applies in oidc mode (a static operator has no session).
| Variable | Default | Meaning |
|---|---|---|
KNEO_DASH_SESSION_SECRET |
change-me |
HMAC signing key over the opaque session id. Required in oidc mode with no usable default — the app refuses to start if left at change-me (fail-fast) so a well-known key can never secure real sessions. Generate with e.g. openssl rand -base64 32. |
KNEO_DASH_SESSION_COOKIE_NAME |
kneo_dash_session |
Name of the session cookie. |
KNEO_DASH_SESSION_TTL_SECONDS |
43200 (12h) |
Absolute session lifetime. |
KNEO_DASH_SESSION_IDLE_SECONDS |
1800 (30m) |
Idle timeout — a session unused for longer is treated as expired (→ re-login), even before the absolute lifetime elapses. Set 0 to disable idle expiry (absolute-only). |
KNEO_DASH_SESSION_PURGE_INTERVAL_SECONDS |
3600 (1h) |
Interval of the background purge of absolutely-expired session rows (keeps the sessions table bounded). Set 0 to disable the loop. |
Persistence (dashboard state store)¶
The dashboard's own state store (operator annotations, saved filters, config; ADR-006) — never platform truth.
| Variable | Default | Meaning |
|---|---|---|
KNEO_DASH_DB_URL |
(unset → local SQLite file) | State-store DB URL. Unset → a local SQLite file (the container defaults it to /var/lib/kneo-dash/state.db). Relocate with e.g. sqlite:////var/lib/kneo-dash/state.db. An external Postgres (postgresql://…, for multi-replica/HA) needs the postgres extra: pip install 'kneo-dash[postgres]'. Backup/restore is covered in the backup & recovery guide. |
CORS / origin¶
| Variable | Default | Meaning |
|---|---|---|
KNEO_DASH_CORS_ORIGINS |
[] (empty) |
Origins allowed by CORS, as a JSON list. Empty by default — dev is same-origin (Vite proxy) and the container serves the SPA itself, so no CORS middleware is added. Set (e.g. ["http://localhost:5173"]) only when hosting the SPA cross-origin. A "*" entry drops credentialed CORS. |
Platform connection¶
The platform URL + API key are not KNEO_DASH_ variables — they live in the kneo-client
profile the BFF binds (resolved per-request in get_client). See Connecting.
| Variable | Default | Meaning |
|---|---|---|
KNEO_URL |
(client default) | Base URL of the Kneo Agent Platform (/v1). |
KNEO_API_KEY |
(client default) | Platform API key (a per-environment service account). |
KNEO_PROFILE |
(client default) | Named kneo-client profile to use (alternative to KNEO_URL/KNEO_API_KEY). |
Observability¶
| Variable | Default | Meaning |
|---|---|---|
KNEO_DASH_METRICS_TOKEN |
(unset → /metrics disabled, 404) |
Bearer token for the operational-telemetry GET /metrics surface. Opt-in; must be ≥ 32 chars (a set-but-short token keeps the endpoint disabled). Generate with e.g. openssl rand -base64 32. The full metric inventory, scrape model, and label rules are in the operational-telemetry spec. |
KNEO_DASH_GRAFANA_URL |
(unset) | Optional Grafana base URL for the Overview deep-link. Unset → no deep-link shown. |
KNEO_DASH_SSE_SEND_TIMEOUT_SECONDS |
30.0 |
Per-send timeout on the trace-stream SSE — a stalled consumer trips it, tearing down the stream (not a max stream duration; a blocked run's tail is intended). |
KNEO_DASH_SSE_MAX_STREAMS_PER_OPERATOR |
5 |
Max concurrent trace-stream connections per operator; a new stream over the cap gets 503 + Retry-After. |
Triage thresholds¶
BFF-derived "needs attention" heuristics (not platform status) surfaced in the runs list and HITL queue.
| Variable | Default | Meaning |
|---|---|---|
KNEO_DASH_STUCK_RUNNING_SECONDS |
120 |
A running run with no updated_at bump for this long is flagged stuck. |
KNEO_DASH_STUCK_BLOCKED_SECONDS |
300 |
A blocked run whose human-task deadline is within this window is flagged stuck. |
KNEO_DASH_HITL_NEAR_DEADLINE_SECONDS |
300 |
A HITL task whose deadline is within this window is flagged near-deadline in the queue. |
See also¶
- Deployment guide — how to run the BFF (container /
pip install). - Connecting — the
kneo-clientprofile and environments.