Live Data for HTML Views

  • Desktop, mobile and web
  • All plans

What it does

An HTML view can read current data when it opens, instead of carrying a copy written once. Agents write a dashboard or a report as a project file, and the file asks for its rows through window.agentsroom: nothing is copied into the file and nothing is stale the next day. It is read-only, off by default and turned on per project, by you. Whatever provider wrote the view makes no difference. The page itself loses direct network access while this is on, so what it reads cannot be sent anywhere by the usual means.

Where to find it

  • Project settings > Capabilities & permissions > Live data for HTML views on the desktop.
  • Phone: the project's … menu > Live data for HTML views.
  • A view that calls the bridge in a project where it is off shows a line above the page with Open the setting.

How to use it

  1. Turn on Live data for HTML views.
  2. Under Databases a view can read, switch on each connection. Nothing is readable until you do: the list shows this project's connections and your account-wide ones, with their Production mark.
  3. Under HTTP endpoints a view can call, add a URL prefix (https://api.example.com/v1/) and, when the API needs one, a header such as Authorization with the value Bearer {{secret:API_TOKEN}}. The secret comes from Commands & connections > Secrets. The desktop adds the header itself; the page never sees it.
  4. Ask an agent for a dashboard, or write the page yourself:
<script>
  const { rows } = await agentsroom.query('Analytics', 'SELECT day, total FROM sales LIMIT 30');
  const stats = await (await agentsroom.fetch('https://api.example.com/v1/stats')).json();
</script>
  1. Open the file: the preview shows Live data, read-only above the page, with how many queries and requests it made. Views that used it in the same setting lists every view that read something, on every machine of your account.

Settings

  • viewDataBridge (project scope, read-only for agents): Project settings > Capabilities & permissions > Live data for HTML views. { enabled, connectionIds, endpoints: [{ urlPrefix, headers }] }. Absent = off. Saved with the project settings, so your other machines follow; the values of the secrets stay in each machine's vault. An agent can read it with settings_get but cannot set it: the agent writing a view must not be able to grant it the access.

Agent tools (MCP)

There is no MCP tool: the page calls window.agentsroom, and any CLI's agent can write such a page. The rules agents read are in the html-views.md etiquette file. agentsroom.query(connection, sql, { database, maxRows }) returns { columns, rows, rowCount, truncated, durationMs }. agentsroom.fetch(url, { accept }) returns { ok, status, statusText, url, headers, text(), json() }. A refusal rejects with an error whose code says why.

Providers

Every CLI: there is no tool to call. The page uses window.agentsroom, and an agent of any provider can write such a page. Agents learn the rules from the html-views.md etiquette file.

Mobile

Same rules and same answers, through the encrypted relay, for a project on the computer the phone is paired with. The page opens in the file viewer with Live data, read-only above it, and the project's … menu has the same setting: the switch, the connections, the endpoints (one header each on the phone) and Views that used it. A project on another machine of the account opens as a plain page. An older desktop or an older phone also opens it as a plain page.

Limits

  • connection-not-allowed: the connection is not switched on in the setting, or does not exist under that name. connection-ambiguous: two connections share the name, use its id.
  • endpoint-not-allowed: no allowed prefix covers the URL. secret-unavailable: the secret is missing on this computer, or cannot be decrypted: the vault is per machine.
  • rate-limited: over 240 calls a minute for one view.
  • Text and JSON only: a binary response is refused. Over 5 MB (1 MB on the phone) is refused too.
  • A query takes at most 60 seconds on PostgreSQL and MySQL.
  • A file in another encoding than UTF-8 shows wrong accents with the bridge on.
  • Relative files (./chart.js) do not load: everything is in the page, or on one of the CDNs listed in Common questions.
  • A link in a view does nothing: opening a URL would be a way out for what the page has read.
  • A view in a worktree outside the project folder opens as a plain page.

Common questions

Can a view change my data? No. Only read statements pass, whatever the connection allows, and on PostgreSQL and MySQL the statement also runs inside a read-only transaction on the server, which refuses a function that would write. HTTP is GET only.

Can the page read my API key or database password? No. The desktop's main process adds the header and opens the database; the page only receives the answer, with the secret's value masked if the server echoes it. A redirect outside the allowed prefix is refused, so the credential is not sent elsewhere.

Can a view send my data to a website? Not by the usual means: with the bridge on, the page has no fetch, WebSocket, remote image, form, pop-up or link to another page, and it cannot navigate away. This is a safety net and not a wall: a page written on purpose to do so could still get out through WebRTC. That is why it is a per-project decision: turn it on only for a project whose files you trust.

Why is my dashboard blank? The page probably loads a script or an image from somewhere the policy blocks, or calls fetch directly. Chart libraries load from cdn.jsdelivr.net, cdnjs.cloudflare.com, unpkg.com, cdn.tailwindcss.com, code.jquery.com, cdn.plot.ly and d3js.org; other files must be inlined in the page. A refused call also shows above the page.

Which files can use it? An HTML file inside the project. A file outside it, in node_modules, vendor and the like, or a symlink pointing out, opens as an ordinary preview without the bridge.

Does it work on the phone? Yes, for a project on the computer the phone is paired with: same rules, same answers, through the encrypted relay. The file must fit the phone's preview (512 KB). Responses over 1 MB are refused there.

Is my data stored by AgentsRoom? No row, statement or response reaches our servers: your computer queries your database and your endpoints directly. The setting and the list of views (their paths inside the project, dates and counters) are saved to your account.

Database Connections, Secret Manager, File Preview.