Custom Dashboard Pages

Build extra dashboard pages with json-render — and wire them to live data, values your agent pushes, a private per-buyer scratchpad, and settings the agent reads.

A custom dashboard page is an extra, owner-authored screen on the Agent Dashboard, built entirely with json-render. Beyond drawing static cards and tables, a custom page can move data in four directions: pull live values on demand, display values the agent pushes, give each buyer a private editable scratchpad, and expose settings the agent reads at runtime.

This page is the complete reference for those four data mechanisms — what to declare, how the data flows, and a worked read / write / update / create example for each.

This page assumes you already know the json-render component and binding model — card, list, stat, input, $state, $bindState, repeat, on.press actions, the “every prop key must be present” rule, etc. All of that lives in Generative UI and applies here unchanged. This page only covers what is unique to custom dashboard pages: the data_sources, data_files, and settings channels.

Custom dashboard pages are a Pro / Business feature. On the Solo plan the editor is unavailable.

Where a page lives and who sees it

A page is one entry in your agent’s custom_dashboard_pages list. Each entry has:

Field	Meaning
id	Stable slug, e.g. study-planner. Immutable — changing it orphans every buyer’s saved scratchpad.
title	Display name. Unique per agent (case-insensitive).
enabled	false hides it from the sidebar. New pages start disabled.
visible_to	owner (only you) or both (you and buyers).
spec	The json-render spec — { root, elements, state }.
data_sources	Live-data + agent-push panels (this page).
data_files	Per-buyer scratchpad slots (this page).
settings	Owner knobs the agent reads (this page).

1. Create & order on /web

   The Dashboard pages card on the Web page is where you add a page (give it a name), toggle it on/off, and drag to reorder. The row order is the order pages appear under SETTINGS in each buyer’s sidebar.

2. Build at /custom-pages/[id]

   The per-page editor is where you write the json-render spec and declare data_sources, data_files, and settings. A live preview renders as you type.

3. Buyers open it at /agent/[name]/dashboard/custom/[id]

   A disabled page, an owner-only page viewed by a buyer, or a missing id all redirect to the dashboard’s Details page rather than 404.

The four data channels at a glance

Everything below writes into — or reads out of — the spec’s state at a JSON Pointer path (/headlines, /settings/paused). The spec then reads state with { "$state": "/path" }, binds editable inputs with { "$bindState": "/path" }, and persists with a button action — exactly as in Generative UI.

Channel	Declared in	Written by	Read by the page	Read by the agent?
Live pull (data_sources, tool/code/url/file/db)	data_sources[]	a curated tool, sandboxed code, an HTTPS API, a per-agent data file, or a read-only DB query — per viewer	{ "$state": "/target" }	❌ never
Agent push (data_sources, writable)	data_sources[]	the agent, via update_widget_data	{ "$state": "/target" }	❌ (it wrote it)
Buyer scratchpad (data_files)	data_files[]	each buyer (private, copy-on-write)	{ "$bindState": "/target" }	❌ never
Owner settings (settings)	settings[]	the owner (on the page or in the editor)	{ "$bindState": "/settings/key" }	✅ get_dashboard_settings + prompt

The agent only ever sees settings. Live-pull results, agent-pushed values, and buyer scratchpads are display / UI state — they are not injected into the agent’s prompt and there is no tool to read them. If the agent needs a value, it must be a setting, or you must collect it through a conversation (collect_form / render_ui).

Free-text prose inputs are disabled on dashboards. A dashboard is not a scratchpad.

Not allowed (rendered disabled, with a disabled tag) on a custom dashboard page — input of:

• kind: "text"
• kind: "textarea"

Allowed (these hold a constrained, sanitised value) — input of kind: "email", "tel", "url", "password", "number", "integer", "select", "checkbox". Their values are cleaned on save (control chars stripped, length-capped).

To collect free-form prose from a user, use a chat form — never a dashboard input. See Per-buyer scratchpad.

How data lands in state, for every channel:

• result_target — a JSON Pointer (/headlines) saying where in state the value is written. Required; must start with /.
• result_path (pull only) — a dotted path into the tool/code result to extract before writing (e.g. rows, or data.items). Note: dotted, not a JSON Pointer.
• Writes are destructive — the value at result_target is replaced, not merged.

---

1. Live data (pull)

A pull data_source fetches data when a viewer opens the page (and on an optional refresh interval). Each viewer’s browser sends only an opaque action_id to the server; the tool name, params, and code never reach the browser. The result is written to state at result_target, where your spec reads it.

There are five kinds — set exactly one per source: a tool call, a code snippet, an HTTPS url, a per-agent data file, or a read-only db query. The first two are shown below; url, file and db work identically here and are documented with simple + full examples on Agent Dashboard — Live Data.

1a. Tool-based source

{
  "tool": "read_rss_feed",
  "params": { "feed_url": "https://hnrss.org/frontpage", "limit": 5 },
  "result_target": "/headlines",
  "result_path": "rows",
  "refresh_interval_sec": 900
}

Allowed tools (read-only): web_fetch, web_search, read_rss_feed, read_recent_tweets, x_read_mentions, x_search_tweets, calculate, or any of your own code tools. params are owner-fixed — the browser can’t change them.

Reading it in the spec — because table.rows and key_value.items are literal-only, render a dynamic array with repeat + $item (see Repeating over a list):

{
  "root": "card",
  "elements": {
    "card":  { "type": "card", "props": { "title": "Latest headlines", "subtitle": null }, "children": ["feed"] },
    "feed":  { "type": "list", "props": { "direction": "vertical", "gap": "sm" }, "repeat": { "statePath": "/headlines", "key": "id" }, "children": ["row"] },
    "row":   { "type": "alert", "props": { "title": null, "message": { "$item": "title" }, "variant": "default" }, "children": [] }
  },
  "state": { "headlines": [] }
}

Seed the result_target path in state (here "headlines": []) so the panel renders cleanly before the first fetch returns.

1b. Code-based source

Use code instead of tool to compute the value in a sandbox (language is "javascript" or "python"). The function returns a value; result_path extracts from it; result_target places it in state.

{
  "code": "function handle(params, ctx) { return { total: 3, items: [{ id: 'a', label: 'Open', value: 2 }, { id: 'b', label: 'Closed', value: 1 }] }; }",
  "language": "javascript",
  "result_target": "/tickets",
  "result_path": "items",
  "refresh_interval_sec": 300
}

Then a single scalar reads cleanly with $state:

{
  "root": "card",
  "elements": {
    "card": { "type": "card", "props": { "title": "Tickets", "subtitle": null }, "children": ["open"] },
    "open": { "type": "stat", "props": { "label": "Open tickets", "value": { "$state": "/tickets/0/value" }, "change": null, "changeType": null, "prefix": null, "suffix": null }, "children": [] }
  },
  "state": { "tickets": [] }
}

1c. HTTPS endpoint, data file, and database sources

Three more pull kinds cover the common “just show me my data” cases without a tool or sandbox:

[
  { "url": "https://api.example.com/stats.json", "headers": { "Authorization": "Bearer …" }, "result_target": "/stats", "refresh_interval_sec": 300 },
  { "file": "metrics.json", "result_target": "/metrics" },
  { "db": { "engine": "postgres", "url": "postgresql://…", "query": "SELECT day AS label, total AS value FROM daily" }, "result_target": "/chart_data" }
]

• url — the server fetches a JSON/XML/text endpoint directly (SSRF-guarded; headers may hold an API key and stay server-side; format: auto | json | xml | text).
• file — a .json/.xml file in this agent’s dashboard_data/ folder, which the agent keeps current via the write_dashboard_file tool (whole document or one JSON-Pointer field at a time). Free.
• db — a read-only Postgres query returning rows; runs in a READ ONLY transaction with row/time caps. Free.

Full walk-throughs — including XML parsing, agent write patterns, and multi-query Postgres dashboards — are on Agent Dashboard — Live Data.

Cost & caching. Pull sources run per viewer and may cost credits (a tool call, a sandbox run, or a flat fee per url fetch — file/db are free), so a server-side cache collapses all viewers + refreshes within refresh_interval_sec into one upstream call. Pick the longest interval you can tolerate. refresh_interval_sec is clamped to 60–86400 s (default 120 s). Non-owner viewers are blocked when the owner’s credit balance is at the floor.

---

2. Agent push (writable panels)

A writable data_source is a panel whose value the agent sets — perfect for a KPI, a status counter, or a chart the agent refreshes from a scheduled run or its own work. No tool runs when a viewer loads it; the browser just reads the last value the agent stored.

Declare it with writable: true and a stable key — and no tool/code/params:

{
  "writable": true,
  "key": "sales_by_day",
  "result_target": "/sales",
  "refresh_interval_sec": 120
}

The agent writes it with the built-in update_widget_data tool (auto-registered for you whenever the agent has writable panels), addressing the panel by its key:

{
  "key": "sales_by_day",
  "value": [
    { "id": "mon", "label": "Mon", "value": 12 },
    { "id": "tue", "label": "Tue", "value": 19 },
    { "id": "wed", "label": "Wed", "value": 15 }
  ]
}

The page reads it from result_target like any other state — e.g. a repeating bar of stats:

{
  "root": "card",
  "elements": {
    "card": { "type": "card", "props": { "title": "Sales this week", "subtitle": null }, "children": ["bars"] },
    "bars": { "type": "list", "props": { "direction": "horizontal", "gap": "md" }, "repeat": { "statePath": "/sales", "key": "id" }, "children": ["bar"] },
    "bar":  { "type": "stat", "props": { "label": { "$item": "label" }, "value": { "$item": "value" }, "change": null, "changeType": null, "prefix": null, "suffix": null }, "children": [] }
  },
  "state": { "sales": [] }
}

The pushed value is served to every viewer, so push only display data — never secrets or raw buyer text. Values are sanitized to inert JSON (functions/symbols become null) and capped at 256 KB total. Each push overwrites the previous value (no history). Steer the agent from your Purpose or Rules, e.g. “After the nightly sync, call update_widget_data with key sales_by_day.”

---

3. Per-buyer scratchpad (data_files)

A data_files slot gives each buyer their own private, persistent, editable value on the page — a checklist, a saved choice, a toggle. It is copy-on-write: your seed is the default until the buyer saves once, after which their copy is theirs forever (changing the seed later never touches an existing buyer’s data). The agent never reads these.

Free-text prose inputs are disabled on a dashboard. A dashboard is not a scratchpad, so input of kind: "text" and kind: "textarea" render disabled on the live page and in the editor preview (with a disabled tag). Every other input kind is allowed and works normally in a scratchpad slot — email, tel, url, password, number/integer, select, checkbox — and their values are sanitised on save. If you need to capture free-form prose from a user, collect it in a chat form (where the value is actually delivered to the agent), not on a dashboard page.

Declare a slot:

{
  "key": "planner",
  "result_target": "/planner",
  "label": "Study planner",
  "seed": { "goal": "", "notes": "", "done": false }
}

Field	Notes
key	[a-z0-9_], 1–40 chars, unique on the page. The save handle.
result_target	JSON Pointer where the value loads into state.
seed	Optional default, copied to the buyer on first save (≤ 256 KB).
label	Optional UI hint.

Read (create): on load the slot resolves to the buyer’s saved value, or the seed if they’ve never saved. The spec binds editable inputs with $bindState and saves with a button whose action is submit + params.savePageData: true (this is repeatable — not a chat submit; the form stays open):

{
  "root": "card",
  "elements": {
    "card":  { "type": "card", "props": { "title": "Study planner", "subtitle": "Private to you — only you can see and edit this." }, "children": ["goal", "notes", "done", "save"] },
    "goal":  { "type": "input", "props": { "kind": "text", "name": "goal", "label": "This week's goal", "placeholder": null, "required": false, "value": { "$bindState": "/planner/goal" }, "options": null, "min": null, "max": null }, "children": [] },
    "notes": { "type": "input", "props": { "kind": "textarea", "name": "notes", "label": "Notes", "placeholder": null, "required": false, "value": { "$bindState": "/planner/notes" }, "options": null, "min": null, "max": null }, "children": [] },
    "done":  { "type": "input", "props": { "kind": "checkbox", "name": "done", "label": "Done", "placeholder": null, "required": false, "value": { "$bindState": "/planner/done" }, "options": null, "min": null, "max": null }, "children": [] },
    "save":  { "type": "button", "props": { "label": "Save", "variant": "primary", "disabled": null }, "on": { "press": { "action": "submit", "params": { "savePageData": true } } }, "children": [] }
  },
  "state": { "planner": { "goal": "", "notes": "", "done": false } }
}

1. Create

   Declare the slot with a seed. First load shows the seed.
2. Read

   On every load the slot resolves to the buyer’s own saved value (or the seed).
3. Update & save

   The buyer edits $bindState inputs; clicking the savePageData button writes their copy. Clicking again overwrites it.

Saving collects the current state of every declared data_files slot on the page and writes each as the buyer’s private copy. Without a save click, edits are lost on reload. Up to 20 slots per page; each value ≤ 256 KB. When you (the owner) view the page, you are your own buyer — your saves go to your own copy.

---

4. Owner settings (the agent reads these)

A settings entry is an owner knob — a toggle, number, text field, or select — that does two things: it can be edited on the page (by the owner only), and the agent reads it at runtime to change its behaviour. This is the one channel that crosses from the page into the agent.

Declare settings:

[
  { "key": "booking_paused", "kind": "toggle", "label": "Pause bookings", "value": false, "help": "When on, the agent stops taking new bookings." },
  { "key": "max_per_day",    "kind": "number", "label": "Max bookings / day", "value": 10 },
  { "key": "tone",           "kind": "select", "label": "Reply tone", "value": "friendly", "options": ["friendly", "formal", "brief"] }
]

Field	Notes
key	[a-z0-9_], 1–40 chars, unique on the page.
kind	toggle → boolean, number → number, text → string, select → one of options.
value	Current value, coerced to kind.
label / help	Optional UI text.
options	Required for select (≤ 50).

Each setting seeds into state at /settings/{key}. The agent reads them two ways:

1. In its prompt — enabled pages’ settings are injected on every turn as a <dashboard_settings> block: - booking_paused (Pause bookings): off.
2. On demand — the get_dashboard_settings tool returns the live values:

// agent calls get_dashboard_settings  ->
{ "ok": true, "settings": { "booking_paused": false, "max_per_day": 10, "tone": "friendly" } }
// or for one key: get_dashboard_settings({ "key": "booking_paused" })  ->
{ "ok": true, "key": "booking_paused", "value": false }

The owner edits them live on the page: bind a control to { "$bindState": "/settings/KEY" } and add a button with params.saveSettings: true. Saving is owner-only (a buyer gets a 403); values are coerced to their kind and persisted to the agent config:

{
  "root": "card",
  "elements": {
    "card":   { "type": "card", "props": { "title": "Booking controls", "subtitle": "Owner only" }, "children": ["paused", "cap", "save"] },
    "paused": { "type": "input", "props": { "kind": "checkbox", "name": "booking_paused", "label": "Pause bookings", "placeholder": null, "required": false, "value": { "$bindState": "/settings/booking_paused" }, "options": null, "min": null, "max": null }, "children": [] },
    "cap":    { "type": "input", "props": { "kind": "integer", "name": "max_per_day", "label": "Max bookings / day", "placeholder": null, "required": false, "value": { "$bindState": "/settings/max_per_day" }, "options": null, "min": 0, "max": 100 }, "children": [] },
    "save":   { "type": "button", "props": { "label": "Save settings", "variant": "primary", "disabled": null }, "on": { "press": { "action": "submit", "params": { "saveSettings": true } } }, "children": [] }
  },
  "state": { "settings": { "booking_paused": false, "max_per_day": 10 } }
}

The agent reads the new value on its next turn (the prompt block and get_dashboard_settings both read live). Settings are per-page; up to 20 per page. Use settings (not a scratchpad) whenever the agent needs to act on the value.

---

Interactive actions (click → run)

Buttons on a custom page can also run work on click — the same runCode and callTool server actions documented for Generative UI. They write their result into state at a target pointer (or show a modal/toast), so you can build “Refresh”, “Search”, or “Recalculate” buttons that don’t depend on a page reload. See Generative UI → Server actions for the full contract.

A complete page (all four channels)

{
  "id": "ops-console",
  "title": "Ops console",
  "enabled": true,
  "visible_to": "both",
  "data_sources": [
    { "tool": "read_rss_feed", "params": { "feed_url": "https://status.example.com/feed", "limit": 3 }, "result_target": "/incidents", "result_path": "rows", "refresh_interval_sec": 600 },
    { "writable": true, "key": "queue_depth", "result_target": "/queue", "refresh_interval_sec": 60 }
  ],
  "data_files": [
    { "key": "notes", "result_target": "/notes", "label": "Shift notes", "seed": { "text": "" } }
  ],
  "settings": [
    { "key": "alerting", "kind": "toggle", "label": "Paging enabled", "value": true }
  ],
  "spec": {
    "root": "root",
    "elements": {
      "root":   { "type": "card", "props": { "title": "Ops console", "subtitle": null }, "children": ["queue", "incidents", "notes", "save", "ownerCard"] },
      "queue":  { "type": "stat", "props": { "label": "Queue depth (agent-pushed)", "value": { "$state": "/queue" }, "change": null, "changeType": null, "prefix": null, "suffix": null }, "children": [] },
      "incidents": { "type": "list", "props": { "direction": "vertical", "gap": "sm" }, "repeat": { "statePath": "/incidents", "key": "id" }, "children": ["incident"] },
      "incident": { "type": "alert", "props": { "title": null, "message": { "$item": "title" }, "variant": "warning" }, "children": [] },
      "notes":  { "type": "input", "props": { "kind": "textarea", "name": "notes", "label": "Shift notes (private to you)", "placeholder": null, "required": false, "value": { "$bindState": "/notes/text" }, "options": null, "min": null, "max": null }, "children": [] },
      "save":   { "type": "button", "props": { "label": "Save notes", "variant": "primary", "disabled": null }, "on": { "press": { "action": "submit", "params": { "savePageData": true } } }, "children": [] },
      "ownerCard": { "type": "card", "props": { "title": "Owner settings", "subtitle": null }, "visible": { "$state": "/settings/alerting", "neq": "__never__" }, "children": ["alerting", "saveSettings"] },
      "alerting": { "type": "input", "props": { "kind": "checkbox", "name": "alerting", "label": "Paging enabled", "placeholder": null, "required": false, "value": { "$bindState": "/settings/alerting" }, "options": null, "min": null, "max": null }, "children": [] },
      "saveSettings": { "type": "button", "props": { "label": "Save settings", "variant": "secondary", "disabled": null }, "on": { "press": { "action": "submit", "params": { "saveSettings": true } } }, "children": [] }
    },
    "state": { "incidents": [], "queue": 0, "notes": { "text": "" }, "settings": { "alerting": true } }
  }
}

Limits & validation

Channel	Per-page cap	Key rule	Other
data_sources	12	writable key: [a-z0-9_] 1–40, unique	result_target JSON Pointer; refresh_interval_sec 60–86400 (default 120); allowed tools only
data_files	20	key: [a-z0-9_] 1–40, unique	seed ≤ 256 KB; copy-on-write
settings	20	key: [a-z0-9_] 1–40, unique	kind enum; select needs options (≤ 50)
agent-pushed value	—	—	sanitized inert JSON, ≤ 256 KB, overwrites

The spec is validated against the json-render catalog on save — an invalid layout is rejected with a precise error. The tool/code/params of a data_source are minted into an opaque action_id and stripped before anything reaches a browser.

Building a page with the AI helper

Instead of hand-writing the JSON, ask the AI Helper: the agent has a build_custom_dashboard_page tool that creates (or updates, by reusing the same page_id) a page with its spec, data_sources, data_files, and settings in one shot, runs the same validation, and enables it immediately. You can then fine-tune it in the editor.

See also

• Generative UI — the json-render component, binding, expression, repeat, and server-action reference (applies here unchanged).
• Web — where pages are created, ordered, and toggled.
• Custom tools — your own code tools, usable as a data_source.
• render_ui / collect_form — collect input in a conversation (the agent does read these), as opposed to a page scratchpad (it doesn’t).