Build your first dashboard

The point of this walkthrough is to build a small, real dashboard with your agent. By the end you’ll have a dashboard with one SQL query, one chart, one filter, and a URL you can hand to a teammate.

This assumes you’ve already connected an agent. If you haven’t, start there.

Create a dashboard

Tell your agent:

Create a new BitBoard dashboard called “first run”.

The agent calls dashboard_create and hands you back a URL. Open it. The dashboard is empty.

Keep both windows open. The browser shows what your agent does, in real time.

Load some data

For this walkthrough we’ll use a longitudinal global GDP dataset hosted on GitHub:

https://raw.githubusercontent.com/datasets/gdp/master/data/gdp.csv

Tell your agent:

Fetch that CSV and import it into the dashboard as gdp.

The agent fetches the file with its own tools, then calls dashboard_import_csv with the body. The CSV becomes a named source in the dashboard’s catalog. Any block, present or future, can query it by name.

Write a query

Tell your agent:

Add a SQL block that sums GDP by year across all countries. Call its output gdp_by_year.

The agent calls dashboard_add_block with type=sql, reading from gdp and writing output_name=gdp_by_year. Downstream blocks reference that name.

You don’t have to memorize the SQL the agent wrote. You can read it, edit it inline, or ask the agent to revise it. Every block keeps its config in the dashboard. The next time anyone opens the URL, the query is right there.

Render a chart

Tell your agent:

Chart gdp_by_year as a line: year on x, total GDP on y. Display it on the dashboard.

The agent adds a chart block pointing at the SQL output, then calls dashboard_set_displayed to put it on the grid. The chart appears. If the SQL output changes later, the chart updates with it.

Add a filter

Tell your agent:

Add a year-range filter and have the SQL block respect it. Display the filter.

The agent adds a filter-daterange block, marks it displayed, and updates the SQL block to read its value as a parameter. The filter renders above the chart. Changing it re-runs the SQL with the new bounds; the chart updates.

Share it

Tell your agent:

Make the dashboard viewable by link.

The agent calls dashboard_set_visibility with link_view. The URL is now shareable. Anyone with it can open the dashboard and see the data, the SQL, and the chart, but they can’t edit. The link also exposes preview metadata, so pasting it into Slack or Linear renders as a card.

What you have

Open the dashboard URL. A filter, a chart, and behind them a SQL block that reads from the ingested source. Each block carries a run timestamp, a status, and an actor (you, via your agent).

This is a live dashboard. Re-running the SQL block re-aggregates against the current source; the chart re-renders with it. Closing the browser doesn’t lose anything. The next time you open the URL, the same dashboard is there.

Where to go next

To connect your warehouse instead of importing public CSVs, see Connect your data.

For the full block reference, see Blocks.

For the full MCP tool surface your agent can call, see MCP tools.