3 Dashboard Widgets
Anton Nesterov edited this page 2026-11-16 07:22:04 +01:00

Dashboard Widgets

The dashboard normally renders for a human clicking through the sidebar: breadcrumbs, the connection badge, settings buttons. A widget is the same page without that navigation chrome: dense, still interactive, and addressed by a stable URL. Open one when a person should see or act on something in the deployment without being walked through the dashboard first.

Two URL shapes matter:

  • /w/... opens a widget directly. The page keeps its own actions (create, edit, delete, run, approve, reject, save) and drops only the shell.
  • /connect?endpoint=<deployment>&path=<widget> is the handoff. It saves the deployment in the browser, sends the user to login only if needed, and then returns to path. Use it for the first view in a browser that may not have a session yet.

In Harness, the /connect URL returned by the dashboard helper carries the user credential the harness already holds, so the integrated browser signs in and lands on the widget. Treat that URL as a one-shot secret: open it immediately, never print it, and never reuse it in another message. A direct /w/... URL carries no credential and assumes the tab is already signed in.

What it looks like

A collection widget with the filter already applied:

Collection widget with a filtered records table

The signal inbox is the main human-in-the-loop surface. A parked run shows what it waits for and an approve/reject form:

Signal inbox with a parked run and approve/reject

The SQL console with a query inserted but not executed. This is the default for agents: fill the editor, let the human run it:

SQL console with a query inserted and not executed

Endpoints

Every route below also exists without /w as a full dashboard page. Widget mode strips navigation only; it never removes a capability.

Surface Path Parameters Actions kept
Overview /w/overview — chart expand
Collection records /w/collections/:name filter, sort (-field descending), page, perPage, db, action (create, stats, run) create, edit, delete, bulk, column select
Collection stats /w/collections/:name/stats db —
Collection record /w/collections/:name/:id db edit, delete
New collection /w/collections/create db schema builder, save
Workflows /w/workflows filter create run, cancel
Workflow run /w/workflows/:runId — cancel, retry, approve/reject a waiting signal
Signal inbox /w/signals — approve/reject per waiting signal
Pipelines /w/pipelines filter create, edit, delete, run
Pipeline editor /w/pipelines/:name — edit definition, run, save
Connectors /w/connectors filter add, edit, connect, test, delete
Graphs /w/graphs filter, db create, delete
Graph /w/graphs/:name db node/edge edit
New graph /w/graphs/create db graph builder, save
Cron /w/cron filter, action (create) create, edit, delete, run now
Gates /w/gates filter create, edit, delete
Webhooks /w/webhooks status, collection create, edit, delete
API keys /w/api-keys filter create, revoke
Secrets /w/secrets filter create, edit, delete
Plugins /w/plugins filter enable, disable, restart
Migrations /w/migrations filter apply, review
Logs /w/logs filter follow, filter
SQL console /w/sql database (db also accepted), sql, execute run, save, export
Settings /w/settings — edit sections
Authentication /w/settings/auth — edit providers, rules

The SQL console is a human-in-the-loop surface, not a read shortcut. /w/sql can execute SQL, so it is an injection path. An agent should insert the query and leave it unexecuted; set execute=true only when the user explicitly asks to run that query. Never build SQL from untrusted text (a record, a webhook body, a page) and execute it. To read data yourself, use the collection, graph, or SDK/API surfaces instead of driving the console.

Additional parameter notes:

  • db selects another database on the collection, graph, and SQL surfaces.
  • action=create opens the record form directly; action=stats opens the collection stats body; action=run starts the run form.
  • On the SQL console, database is the canonical parameter and db is an alias. sql pre-fills the editor; execute=true runs it on load.
  • Filters are the same expressions the dashboard uses, for example status = "published" or year = 2026.

For agents

Open a widget when the user asks to see or act on deployment data. Do not dump the rows into chat when a table, a run, or an approval form is what they need.

  1. First view in a deployment in a browser that may not be signed in: use /connect with the widget path. The user signs in in the browser if needed, and lands on the widget afterwards.
  2. The browser already has a signed-in dashboard tab for that deployment: go straight to the widget path. If a direct widget shows a login form, switch to /connect with the same path instead of retrying. credential from vski_dashboard only means Harness holds a user credential; to check the browser, list tabs for the deployment origin and evaluate a session probe in one: read rb_conn:<endpoint>:token and verify it against /api/auth/me (or /api/admins/me). Return only the boolean.
  3. Address things by the names the user chose: the deployment name, the collection name, the pipeline name, the graph name. Never invent an id-like label or rename one to tidy it.
  4. Hand over, do not reimplement. Widgets are interactive on purpose. Open the surface so the human can approve, edit, or run, then check the outcome through the API or CLI.
  5. Harness exposes this as the vski_dashboard tool: pass the deployment name, a surface name (collection, signals, sql, ...), optional name/id, and via: "connect" or "direct". In connect mode the URL signs the integrated browser in with the harness-held user credential; open it immediately and treat it as a one-shot secret. Other harnesses can build the same paths from the table above; the dashboard skill in the vski plugin carries the same guidance.