Artifacts: pages an agent publishes for people

An artifact is one page that people of your organisation open on LakehouseBox: a dashboard, a report, a map. You publish its HTML and name the catalogs it reads. The page holds no data: its script reads the tables live, in the browser of whoever opens it, with that person's own permissions.

lhbox artifact publish garden.html --title "The garden, last 14 days" --catalog garden   # a new page: prints its address
lhbox artifact ls                                                # the artifacts this key can see
lhbox artifact pull Xk3f9QaZ garden-page                         # its files into a folder, to change them
lhbox artifact publish garden-page --note "Added soil moisture"  # the next version of the same page

A new artifact is private to the person behind the key that published it. The person: opens the address the publish printed, and shares the page from there if others should see it. An agent never shares a page.

An artifact has one id, eight letters and digits (Xk3f9QaZ), and one address, https://lakehousebox.com/a/<id>, whoever it is shared with: the API's artifact_id and url, lhbox artifact ls and the MCP tools all name it so, and its id and address do not change when its sharing does. Opening the address does what the sharing allows. A public page opens for anyone, with no account. Any other page opens in the account after a sign-in, for the people who may see it; for anyone else the address answers exactly as for an id that does not exist. While a page is public its address also carries the words of its title (/a/<id>/<title words>); the id alone decides which page opens, and a private page's address never carries its title. The longer ids artifacts had before (a_ and 22 characters) and the addresses built on them still open the same page.

Writing the page

The page is plain HTML, CSS and JavaScript. It loads one module, the runtime, from the page's own host:

<!doctype html>
<meta charset="utf-8">
<title>Readings</title>
<h1>Readings, last 14 days</h1>
<div id="total">Loading…</div>
<script type="module">
import { lhbox } from '/_lhbox/lhbox.js';
lhbox.panel(document.getElementById('total'), async (el) => {
  const { rows } = await lhbox.query(
    "SELECT count(*) AS n FROM garden.main.readings WHERE ts > now() - INTERVAL 14 DAY");
  el.textContent = rows[0].n + ' readings';
});
</script>
call what it does
lhbox.query(sql, {params}) Runs one DuckDB statement in the viewer's browser and answers {columns, rows}. columns is a list of {name, type}, in the statement's order, with a DuckDB type name such as bigint, double, varchar, date, timestamp or decimal(18,3). Each row is an object keyed by column name. params fills the ? marks of a prepared statement.
lhbox.panel(element, fn) Runs fn(element). When the viewer cannot read a catalog the function queries, the element shows a note naming it, such as "You can't read garden", and the rest of the page keeps working.
lhbox.duckdb() The engine's connection with the catalogs attached, for Arrow results and prepared statements.
lhbox.asset(path) The address of one of the artifact's own files that loads now. Use it for a file fetched late, such as an image shown on a click.
lhbox.open(url) Asks LakehouseBox to open a link. The person sees the address and confirms before a new tab opens.
lhbox.download(name, data) Offers a file the page made, such as a CSV of a result: data is a Blob, a string or bytes, at most 25 MB. The person sees the file's name and size and confirms before it is saved. Answers a promise: true once saved.
lhbox.copy(text) Puts text on the clipboard, at most 1 MB. Call it from a click or a key press. Answers a promise: true once copied.
lhbox.setState(text, {push}), lhbox.onState(fn), lhbox.state The page's own place (a view, a filter, a selection) as one string of at most 2,000 characters, kept in the address of the page around it, so a reload, a copied link and Back return to it. setState replaces the address; {push: true} adds a step to the browser's history. onState(fn) hears the address change (Back, Forward, a link) and returns a function that stops it. lhbox.state is the place the page was opened at, once lhbox.ready() has resolved (below).
lhbox.link The address that opens this page at its current place, for a "copy link" button: lhbox.copy(lhbox.link). It is the page's one address with its place, https://lakehousebox.com/a/<id>#s=<state>, and for a public page the words of its title after the id, https://lakehousebox.com/a/<id>/<the title's words>#s=<state> (the id decides which page opens; the words follow the title). Without a state, the part from #s= is left out. It follows setState, Back and Forward, and a change of the page's sharing. It never grants access: whoever opens it signs in, or opens the public page, and sees what they may read.
lhbox.ready() A promise that resolves with lhbox once LakehouseBox has answered the page, with lhbox.state and lhbox.link set. It rejects with code: 'no_viewer' when the page is opened by itself, outside LakehouseBox.
lhbox.engine The engine the page runs: duckdb-wasm-2.0.0, or duckdb-wasm-1.5.6 for a version published before 13 November 2026 (below).
lhbox.catalogs, lhbox.unreadable, lhbox.viewer The catalogs attached, the ones this viewer cannot read with the reason, and the viewer's name.
  • Name tables catalog.namespace.table, as in lhbox query and the MCP query tool. Test each statement there first: the same SQL runs in the page. Another organisation's public catalog <handle>/<catalog> is read as <handle>_<catalog>.namespace.table.
  • Wrap every chart, table and number in lhbox.panel. Never assume the viewer reads what you read.
  • Aggregate in SQL and return what the page draws. A phone opens this page: thousands of rows, not millions.
  • Show the title and the layout at once, and fill the panels as the queries answer. The engine starts on the first query.
  • Nothing is cached between calls. Keep a result in a variable to use it twice.
  • Values arrive ready for JSON. A timestamp is an ISO 8601 string in UTC and a date is YYYY-MM-DD. A 64-bit integer or a decimal that does not fit a number exactly is a string.
  • A page laid out to the window, such as a full-screen map, says <meta name="lhbox-layout" content="fill">.
  • Inside the frame, location.hash is not the address people see or share. A page with views of its own keeps its place with lhbox.setState and reads it back from lhbox.state and lhbox.onState.
  • lhbox.state and lhbox.link are empty until lhbox.ready() resolves. A page that reads them as the module loads never opens at the linked place (the console says so). Wait for the answer first: const { state } = await lhbox.ready(); showView(state); lhbox.onState(showView);
  • The frame cannot save files or reach the clipboard by itself (a link with download, navigator.clipboard): use lhbox.download and lhbox.copy.

The engine

The page's SQL runs in DuckDB 2.0.0, compiled to WebAssembly, in the viewer's browser. A version keeps the engine it was published with: versions published before 13 November 2026 run DuckDB 1.5.6, and publishing the page again moves it to 2.0.0. Both read the same tables with the same SQL. A query over many files of a partitioned table is the one you will notice: on a page that reads a year-partitioned table of 39 files, that query took about 1 s on 2.0.0 against 3 s on 1.5.6 (Chromium; measured 13 November 2026).

Time

The page's engine runs in UTC, as the query tools do, so the same statement answers the same in both. now() - INTERVAL 14 DAY, date_trunc('day', ts), ts::DATE and strftime(ts, …) work on a TIMESTAMP WITH TIME ZONE column, and a day is a UTC day for every viewer.

For the viewer's own time, say so in the page: ts AT TIME ZONE 'Europe/Madrid' in SQL, or format the ISO string in JavaScript with new Date(value).toLocaleString().

Two forms never depend on the session's zone, if you prefer them: a literal bound, ts > TIMESTAMPTZ '2026-10-29 00:00:00+00', and the day number, epoch_ms(ts) // 86400000.

What the page can reach

The page runs in a sandboxed frame on a host of its own, apart from the account page.

it can it cannot
read the catalogs it names, as the viewer read a catalog it did not name, or one the viewer cannot read
load its own files and assets, fonts included send a request to any other host: no fetch, no external images or fonts
load a script or a stylesheet from cdnjs.cloudflare.com, cdn.jsdelivr.net or unpkg.com, with a <script>, a <link> or an import, also one added while the page runs load a script from anywhere else, or fetch anything from those three hosts: a library that downloads its own parts from there (a worker, WebAssembly, data files) fails
draw with inline SVG, canvas, CSS and its own JavaScript use cookies, storage, forms or popups, or leave its frame: localStorage throws a SecurityError
show basemap tiles from tiles.lakehousebox.com see anything of the account page or the viewer's session

A font is an asset: put the .woff2 file in assets/ and name it in the page's CSS as @font-face { font-family: 'Source Sans 3'; src: url(../assets/source-sans-3-400.woff2) format('woff2'); }. Fonts from Google Fonts or any other host are blocked.

Ship the libraries the page uses as its own files: <script src="d3.min.js"> beside index.html keeps working whatever the library fetches and whichever host is down. lhbox artifact check names, by file and line, each address in the page's files that the frame blocks (file_other_host).

With the browser's developer tools open, a script loaded from one of those hosts can show a connect-src violation in the console: the developer tools fetch the script's source map (the //# sourceMappingURL= line at its end), and that fetch is blocked. The script itself loaded. A copy shipped with the page, its .map beside it or that line removed, keeps the console clean.

Put nothing private in the HTML. Whoever the page is shared with can read its source, so no secret, no copied rows and no personal data belong in the file. Data stays in the tables, and each viewer sees only what they may read.

Making a good page

What makes a page people come back to, learnt building Embalses (the worked example: how it was made). A publish answers warnings for what it can see of these, each with the fix and a link back here.

Draw the page before the data

Show the title, the layout and placeholders shaped like what comes (cards, rows, a grey map) at once. Clear every placeholder when its query answers, and when it fails, or the page shimmers for ever.

Say how fresh the data is

Show when the data was last updated, from a timestamp in the data itself, in the reader's time zone: new Date(value).toLocaleString().

Store the tables for the page

How fast a page opens depends more on its tables than on its code. Give a page tables compacted and pre-aggregated to what it draws, and measure the second open as well as the first.

Give every view a state

Give each view, filter and selection a state from the start with lhbox.setState, and open at lhbox.state once lhbox.ready() resolves; location.hash is not the address people share. A page that replaces an older site maps the old links to a state, so links already shared keep working.

A public page's preview comes from the publish, never from tags in the page: Open Graph, Twitter, JSON-LD and icon tags in the HTML do nothing. Publish with --description and --thumbnail (When the link is shared).

Name the sources, offer the data

Name each source and its licence on the page. Offer what a chart shows as a table and as a CSV (lhbox.download), not only as a chart.

Read everything from the catalog

The page reads its data with lhbox.query: no rows copied into the HTML, no requests to other hosts, map outlines as GEOMETRY columns of a table. Ship images, fonts and a basemap's .pmtiles as assets; data the page queries belongs in a table. The one exception is a small file for the first view, written from a table (Draw before the engine is up).

Keep the source in git

Keep the page's files in a repository and publish from CI, the commit's subject as the version's note: lhbox artifact publish page/ --note "$(git log -1 --format=%s)".

Fit a phone and the reader's language

Lay the page out for a phone's width (<meta name="viewport" content="width=device-width, initial-scale=1">), name its language (<html lang="es">) and format numbers and dates in the reader's language (toLocaleString(), Intl.NumberFormat).

Writing a fast page

What made Embalses fast on a phone. The numbers were measured on that page in November 2026; a page of yours depends on its own tables and code.

Draw before the engine is up

The engine starts on the first query, and on a phone that first answer takes seconds. Draw the first view from a small file shipped with the page, and let the live data replace it: fetch('outlines.json') beside index.html, written from the table the page reads. On Embalses a 41 KB (compressed) file of outlines drew the map in about 0.6 s, where it had waited for the engine and a query. Keep the file to what the first view draws, and write it again when its table changes.

The frame has no storage (localStorage throws), so a result cannot be kept for the next visit: the small file is what makes every visit's first view fast.

No layout shift

Give every element its final size before its data comes:

  • A canvas sized by the script gets the same shape in CSS: canvas { width: 100%; aspect-ratio: 1 / 0.8 } when the script draws it 0.8 times as high as it is wide.
  • A placeholder is as long as the value that replaces it: 000.0 hm³, not ….
  • A table's placeholder has the real header and the real number of rows, each of the real height.

With these three, Embalses' layout shift on a phone went from about 0.21 to about 0.02.

Load a library when it is first needed

Load what only a click or a later view uses at that moment, not with the page: add its <script>, or import() it, from the code that needs it, and keep the promise so it loads once. Ship it as a page file (What the page can reach).

Put each file where it belongs

A folder's page/ takes .html .css .js .json .geojson .csv .svg, at most three folders deep; assets/ takes only .png .jpg .jpeg .webp .gif .avif .woff2 .parquet .pmtiles .mp4, directly in it. A .json, .js or .geojson in assets/ stops the publish before anything is sent; lhbox artifact check <folder> says so without publishing.

Give each click one small table

The first read of a table costs its metadata, about 300 to 600 ms per table on Embalses, and the page's queries run one at a time: Promise.all over three queries takes as long as the three in a row. So:

  • Precompute what a click shows into one small table with a derived sink, with ORDER BY the key the click filters on, so a filtered read skips most of the file.
  • Read a small lookup table once and keep its promise; do not query it again on every click.
  • Start the click's query on hover (pointerenter).
  • A few seconds after the page is up, read the tables the next click is likely to need.

On Embalses a click on a municipality went from 4.2 s to 0.87 s the first time, and 60 ms after that.

Refresh a derived table when its source changes

A derived table built only from reference data changes only when that data is loaded again. Run its sink daily (--every 1d) and once right after each reload (lhbox sink run <sink> --wait), not every hour.

Test the page as visitors get it

Open the published page in headless Chrome at a phone's size, and read the layout shift and the console of the page's frame: a request the frame blocks shows there as a Content Security Policy error. With Playwright (npm install playwright-core) and the Chrome installed on the machine:

// node check-page.mjs https://lakehousebox.com/a/<id>   (a public page; a private one needs a signed-in session)
import { chromium } from 'playwright-core';
const browser = await chromium.launch({ channel: 'chrome' });
const context = await browser.newContext({ viewport: { width: 390, height: 844 }, isMobile: true, hasTouch: true });
await context.addInitScript(() => {           // runs in the artifact's frame too
  window.__cls = 0;
  new PerformanceObserver((list) => {
    for (const e of list.getEntries()) if (!e.hadRecentInput) window.__cls += e.value;
  }).observe({ type: 'layout-shift', buffered: true });
});
const page = await context.newPage();
page.on('console', (m) => { if (m.type() === 'error' || m.type() === 'warning') console.log(m.type(), m.text()); });
await page.goto(process.argv[2], { waitUntil: 'load' });
await page.waitForTimeout(8000);               // time for the queries to answer
for (const f of page.frames()) console.log(new URL(f.url()).host, 'CLS', await f.evaluate(() => window.__cls));
await browser.close();

It prints one line per frame: the page around it, then the artifact's frame, whose layout shift is the page's. Run on Embalses on 19 November 2026, it printed 0.027 to 0.033 for the frame over three runs, and no console error.

Publishing

Name every catalog the page's SQL reads. You can only name catalogs you read as a whole: a grant on some namespaces or tables is refused, and so is a catalog your key was not given.

from how
the CLI lhbox artifact publish PAGE --title TEXT --catalog CATALOG: one HTML file, or a folder
the API POST /v1/artifacts with {"title", "catalogs", "html"} publishes in one call
an MCP host the publish_artifact tool, with read_artifact and list_artifacts
a hosted agent the same three tools, when its definition has artifacts

A page of several files is a folder: page/ holds index.html and the other page files, assets/ holds images, fonts and other binary files, and the page refers to an asset as ../assets/<name>. lhbox artifact pull writes that folder and lhbox artifact publish <folder> publishes it back as the next version. A folder published as a new artifact gets an artifact.json too, with the artifact's id and catalogs, so publishing the same folder again makes its next version, not a second artifact.

An asset is stored under the SHA-256 of its content (assets/<sha256>.woff2), and the publish rewrites each assets/<name> in the page files to that stored name. A pulled page therefore does not match its source file for file: compare the page with your source after replacing the stored names, or keep the source as the one you edit.

Every publish answers warnings: a list, empty when there is nothing to say, of {code, message, remedy, docs} about the page's index.html (no lang, no viewport, tags a preview never reads, location.hash, requests and loads from hosts the frame blocks, a public page without a description or a thumbnail, assets over 2 MB the page loads). They never stop a publish: fix them in the next version. The CLI prints them after the address, and docs links the section of Making a good page that explains each.

lhbox artifact check ARTIFACT (GET /v1/artifacts/{id}/check) checks the published version without running it. It lists as problems the files the page files refer to that the version does not hold (src and href, CSS url() and @import, relative imports, lhbox.asset('…') with a literal path), and the catalogs it names that nobody reads through it: catalog_gone, author_lost_read (whoever published it no longer reads the catalog), not_public. It also gives the publish's warnings, file_other_host for each address in any page file that the frame blocks (with its file, line and host), a version still on the older engine, and the size against the limits. Each entry of catalogs says whether the catalog is public now and how the page's viewers read it, read_as: public (as anyone reads a public catalog: on a public page, or another organisation's catalog named <handle>/<catalog>) or viewer (with each viewer's own access). It exits 1 when there is a problem, so a CI step can run it after a publish; warnings do not change the exit code. A path the script builds while it runs is not checked, and neither is what the page does when it runs: console errors, failed queries and timings show in the browser's developer tools on the open page (Test the page as visitors get it).

lhbox artifact check <folder> checks a folder on disk before it is published, with no request: a file of a type page/ or assets/ does not take, or a layout publish refuses, is a problem (exit 1), in the words the publish would stop with.

Over the API a folder is three steps. POST /v1/artifacts without html starts a pending version. Each file goes up with PUT /v1/artifacts/{id}/versions/{version}/files/{name}. POST /v1/artifacts/{id}/versions/{version}/publish shows it. Nothing is shown until that last call answers. A pending version that is not published within 24 hours is deleted, and an artifact keeps at most three pending versions: starting a fourth deletes the oldest.

Versions

To change a page, publish its next version: pass artifact_id to the API and the MCP tool, or --artifact to the CLI. With --artifact and no --catalog, the CLI names the catalogs the artifact reads now.

  • A version is the whole page. What you do not send is not in it, except the artifact's assets, which a version sent in one call goes on naming.
  • Read the page before you change it: lhbox artifact pull, the read_artifact tool, or GET /v1/artifacts/{id}/files, which answers the page files as text. A file marked truncated or omitted is not the whole file: do not publish a version built from it. lhbox artifact pull always writes every file whole.
  • Add a note, one line saying what changed: --note, or "note" in the body. People see it in the list of versions.
  • One page per subject. Keep it current with new versions instead of publishing a second page.
  • A key or an MCP connection publishes versions of the artifacts it made. A hosted agent publishes versions of the ones it keeps (below). A person publishes versions of theirs and of the ones their agents made. Anyone else is refused.

Who sees it

  • A new artifact is private: only the person it belongs to opens it.
  • The person shares it on the page itself: with named members of the organisation, with the whole organisation, or with anyone on the internet (below). An agent's key, an MCP connection and a hosted agent cannot share or duplicate an artifact. They can delete one they may publish to: Deleting a page.
  • Sharing lets someone open the page. It gives them no data: a viewer who does not read a catalog sees a note such as "You can't read garden" in the panels that query it. The Share panel says so for each person before they are added.
  • A page is opened by a person signed in on the account page. An API key cannot open one.

Deleting a page

A deleted page goes to the trash. Nobody opens it from then: its address answers as if it never existed. It can be restored for 30 days, with the same id and address, and then its files are removed.

lhbox artifact delete Ab12Cd34 --yes      # asked on a terminal without --yes
lhbox artifact ls --deleted               # the trash
lhbox artifact restore Ab12Cd34
  • Who deletes: the person it belongs to, and an admin of the organisation. A key, an MCP connection (delete_artifact) and a hosted agent (delete_artifact) delete the pages they may publish to: the ones they made, and for a hosted agent the ones it keeps. Anyone else is refused.
  • A page that is public or shared with people can be deleted. The answer says who lost access: anyone on the internet, every member of the organisation, the people it was shared with by name.
  • When an agent or an admin deletes a page, the person it belongs to gets an email with the way to restore it (at most five such emails an hour; the Deleted list has every one).
  • A restored page is private, whatever it was. The people it was shared with by name keep it; its owner shares it again from the page. Whoever may delete a page may restore it, except through an MCP connection.
  • DELETE /v1/artifacts/{id}, POST /v1/artifacts/{id}/restore, GET /v1/artifacts?deleted=true.

Making a page public

A public page is opened by anyone on the internet, with no account, at its public link. Around the page we show its title, who published it and Report, and Follow where its owner lets visitors subscribe to the page's agent. The LakehouseBox logo opens our site in a new tab. Search engines are asked not to index it.

Public pages are turned on per organisation. Where they are on, the Share panel's General access offers Anyone on the internet.

  • Only the page's owner makes it public, signed in on the account page. A key, an MCP connection and a hosted agent cannot, and neither can an admin for someone else's page.
  • The owner needs a verified address, and the organisation's setting for publishing catalogs has to let them publish: admins by default.
  • A public page reads public catalogs only. If the page names a private catalog, the panel lists it with its tables and its size, and making the page public makes that catalog public too. Anyone on the internet can then read and copy every table of it, not only what the page shows. You confirm each catalog by typing its name.
  • A public page keeps only the version it shows. Its earlier versions are deleted when it becomes public, and each new version replaces the one before. Whoever opens the page can read its files, so put nothing in them you would not publish.
  • An organisation makes at most 10 pages public a day.
  • While a page is public, a version that names a catalog which is not public is refused with 409 artifact_public_private_data. An agent goes on publishing versions of a public page under that rule.
  • If a catalog is made private again while a public page reads it, visitors see "This catalog is no longer public" in the panels that query it, and the owner is told on the page.

Making the page private again takes it off the web at once. The panel then offers to make private the catalogs that going public had published, and no others.

A page stops being public when it is deleted, when its owner leaves the organisation, and when public pages are turned off for the organisation. A restored page is private.

Making a page public is also where its owner decides whether visitors may subscribe to its agent's updates: Letting visitors follow a page.

over the API
PATCH /v1/artifacts/{id} with {"sharing": "public", "dry_run": true} answers the plan: each catalog, and for a private one its tables, its size and the name to confirm
PATCH /v1/artifacts/{id} with {"sharing": "public", "confirm_catalogs": {"<warehouse id>": "<name>"}} makes it public, from a browser session
PATCH /v1/artifacts/{id} with {"sharing": "private", "unpublish_catalogs": ["<warehouse id>"]} makes it private, and those catalogs with it
GET /v1/artifacts/{id} url and, while the page is public, public_url, the same address (https://lakehousebox.com/a/<id>/<the title's words>), and for its owner public.copies
PATCH /v1/artifacts/{id} with {"follow": true, "follow_ack": {"catalogs": ["<warehouse id>"], "integrations": false}} lets visitors subscribe to the page's agent, from a browser session; {"follow": false} stops it
GET /v1/a/{id}/card the share card, with no account: title, description, url, image (url, width, height, alt, or null)
GET /v1/a/sitemap.xml every public page, as a sitemap, with no account

A public page's link shows a preview in chats and posts (WhatsApp, LinkedIn, Slack, X): the page's title, a line of description and an image. The page's head carries them for every public page, with nothing to set up. Without your own description the line names your organisation; without your own image the preview shows LakehouseBox's.

To choose them, publish with a description and a thumbnail, an image in the folder's assets/ (1200 × 630 pixels, PNG, JPEG or WebP, at most 5 MB):

lhbox artifact publish site/ --description "Spain's reservoirs and rain, live." --thumbnail card.png

artifact.json keeps both, so the next lhbox artifact publish site/ sends them again. Over the API they are description (one line, at most 300 characters) and thumbnail (the image's stored name, assets/<sha256>.<ext>) in POST /v1/artifacts. A version that does not send them keeps the ones before, so a hosted agent's updates keep the card; --description "" removes the description. A thumbnail over 5 MB is refused when the version is published. A preview follows a change to the page (renamed, made private) within a minute. A self-hosted install serves the page without the preview tags.

In search engines

A public page is open to search engines: its head carries its title, description and canonical address, and it is in the sitemap at https://api.lakehousebox.com/v1/a/sitemap.xml, which the site's robots.txt names. A page that is not public tells search engines not to list it and is never in the sitemap; one made private leaves it within the hour.

Use this in your account

A person with an account can make a private copy of a public page in their own organisation (the public page itself has no button for it). The copy reads the same public catalogs under the same names, so it works at once, and it says where it came from. Nothing but the page is copied. The owner of the original sees how many copies were made. Over the API it is POST /v1/artifacts/{id}/duplicate on a public page, with {"org_id"} to choose the organisation.

Your organisation's brand

An organisation on the enterprise plan can put its own logo, name and link above its public pages, where LakehouseBox's logo is otherwise. The bar keeps Report and a small Made with LakehouseBox link whatever the brand says.

An admin sets it on the account page, under Settings › General › Public page brand, or over the API:

  • The link must be an https address on a domain your organisation has verified by DNS (Settings › General › Email domains), or on a subdomain of one: https://datos.madrid.es/ once madrid.es is verified. If the domain stops being verified, the bar stops showing the link and keeps the name and logo.
  • The logo is a PNG, JPEG or WebP image, at most 200 KB and 2048 pixels a side, shown 28 pixels tall. SVG is refused. A transparent PNG about 200 pixels tall looks best.
  • If the organisation leaves the enterprise plan, its pages show LakehouseBox's bar again. The brand is kept and comes back if the plan does.
over the API
GET /v1/orgs/{org}/brand the brand, whether public pages show it, and the verified domains a link may point to
PATCH /v1/orgs/{org}/brand with {"name": "…", "link": "https://…"} sets the name and the link; null clears one
PUT /v1/orgs/{org}/brand/logo with the image as the body sets the logo
DELETE /v1/orgs/{org}/brand/logo, DELETE /v1/orgs/{org}/brand removes the logo, or the whole brand

Reports

Report on a public page sends us what the visitor says is wrong with it. We can take a page off the web. Its owner then sees that it was taken down and why, and cannot make it public again until we lift that.

Letting visitors follow a page

A visitor of a public page can subscribe by email to what the page's agent writes about it. They follow the agent, for that page: its updates, and the note of each version it publishes.

The page's owner decides, and it is off until they turn it on. The choice is offered when the page is made public and afterwards in the Share panel, and only for a page that has an agent.

Nobody reads an update before it is emailed. Not the owner, and not us. So before the owner says yes, the panel names what the agent reads that is not public: the private catalogs it reads or has read, and whether it uses a person's connected accounts. What the agent writes may carry what it read there. If the agent is later given another private catalog, the emails stop until the owner confirms again.

  • Only the owner turns it on, signed in on the account page. A key, an agent and an admin cannot. The owner or an admin turns it off.
  • Turning it off stops the emails at once and keeps the list. So does making the page private, giving the page to another agent or taking it from its agent, and a takedown. The owner turns it on again on purpose.
  • The emails also stop while public pages are turned off for the organisation.
  • While the page is deleted, nobody subscribed gets an email. Its addresses are deleted with its files, 30 days after; a page restored before then keeps them, and the emails start again when its owner turns them on again.
  • The owner sees how many people subscribed and the last things the agent said. The owner never sees an address.
  • A page takes at most 200 subscribers.

For a visitor:

  • Follow asks for an email address. We send one email with a link to confirm it. Nothing else is sent to an address until that link is followed.
  • Every email has the page's link, the organisation that published it, "Made with LakehouseBox" and a link to unsubscribe. Mail apps that show an unsubscribe button use the same link.
  • Unsubscribing erases the address from the page's list.
  • No account is made.

The answer to a subscription is always the same, whether the page takes subscribers or not and whether the address is already subscribed. An address is sent at most one confirmation per page a day and three a week.

over the API
GET /v1/artifacts/{id} follow: on, live, and for the owner agent, agent_reads, subscribers, updates
PATCH /v1/artifacts/{id} with {"follow": true, "follow_ack": {...}} turns it on. follow_ack repeats follow.agent_reads: the ids of its catalogs and its integrations. 400 confirmation_required carries what the agent reads now
POST /v1/a/{id}/open follow: {"agent": "<name>"} when visitors may subscribe, else null
POST /v1/a/{id}/subscribe with {"email": "<address>"} no account needed; always 202

A hosted agent that keeps a page

A hosted agent whose definition has artifacts gets publish_artifact, read_artifact, list_artifacts and post_update. A new agent has it; turn it on for an older one with lhbox agent update <name> --artifacts.

  • A page the agent publishes is private and belongs to the person who created the agent.
  • The agent reads and updates the pages it keeps: the ones it published and the ones it was given. It lists those and no others.
  • The person who owns a page gives it to an agent they manage on the page's menu, or with PATCH /v1/artifacts/{id} and {"agent": "<agent name>"}. The answer names the page's catalogs that agent cannot read: it cannot publish a version that reads them until it is given the catalog.
  • The person takes a page back the same way ({"agent": null}), or gives it to another agent. From then the agent that kept it no longer lists, reads or updates it (404 artifact_not_found), even when it made the page. It can still publish a new page: to stop that, change its task or turn its artifacts off (lhbox agent update <name> --no-artifacts).
  • A run publishes at most 5 versions. A test run checks the page and publishes nothing.
  • post_update says one short thing about a page the agent keeps: at most 1,200 characters, with a little formatting and links only to that page (how an update looks). It goes to the people who already get the agent's notices, as one of its notices of the day (it leaves the run's own notice free). Where the page's owner lets visitors follow the page, it is also emailed to the page's subscribers, as written. At most one update per page in a run, 3 in a run and 2 per page a day. A test run posts nothing.
  • The agent publishes one self-contained HTML file. It cannot update a page made of several page files, and its version never renames the page: the title is its owner's.
  • The agent's own access decides what its pages show. When the agent is deleted, or loses a catalog, the pages it published last show no data from that catalog. The person who owns the page re-owns it from the note the page shows, and it reads what they read.

How an update looks

An update is written once and shown the same way in the email's HTML, in its plain-text part (for mail apps that show only text), in the email to the people who get the agent's notices and in the owner's list on the account page. A version's note follows the same rules, on one line of at most 200 characters (a longer one is cut there).

you write in the email and the owner's list in the plain-text part
a line break a line break; an empty line starts a new paragraph (more than one empty line counts as one) the same
**three stations** three stations (bold) three stations
lines that start with - a bulleted list the same lines, - and all
[see your town](<the page's address>#s=<place>) "see your town", a link to that place on the page see your town (the address)
the page's bare address the address, as a link the address
  • The only link is to the page itself: its address as url gives it (https://lakehousebox.com/a/<id>/<the title's words>, or https://lakehousebox.com/a/<id>), optionally with a place on it, #s=<state> (the place lhbox.link gives: letters, digits and - _ . ~ % ! * ', not ending on . ! * '; write ( and ) as %28 and %29). Any other link or address, a link's words that are themselves an address ([https://…](<page>)), an address of another kind (mail, data or script) or an image is refused with 400 update_has_link, and a version's note that carries one is published and emailed to nobody.
  • A bare address must stand on its own: a space, the end, a closing mark or ** after it (., ,, ) are fine, and are not part of the link).
  • Nothing else is formatting: HTML, headings, italics, numbered lists, tables and images are shown as the characters written (<b> reads <b>). A link inside bold stays a link.
  • The 1,200 characters count the text as the agent sent it, the markup included.

When it fails

error what it wants
403 artifact_needs_catalog_read You hold only namespaces or tables of a catalog the page names. Ask an admin for read on the catalog, or leave it out.
403 forbidden, 404 warehouse_not_found, 403 connection_not_granted A catalog the page names is not one this key reads. Name a catalog you read, or have the person give this key the catalog.
403 artifact_not_yours The artifact was published by someone else. Publish a new one, or have its owner publish the version.
404 artifact_not_found No artifact you can see has that id. lhbox artifact ls lists yours.
403 claim_required The organisation was made without an account. The person keeps it first: lhbox claim.
409 artifact_limit The organisation keeps 200 artifacts. Publish a version of an existing one, or have the person delete one.
409 artifact_version_superseded Another version of the page was published while this one was being sent. Send it again.
409 artifact_version_gone The pending version was deleted (unpublished for 24 hours, or a fourth was started). Start the version again.
409 artifact_author_lost_read A copy of a page whose publisher no longer reads one of its catalogs. Someone who reads it publishes the page again, or an admin takes it over; then copy it.
413 artifact_too_large A page file is over 2 MB, an asset over 20 MB, or the version over 25 MB. Read the data from a table instead of shipping it.
415 artifact_type_refused The file type is not one an artifact holds. See the limits below.
429 rate_limited More than 30 versions in an hour from one key. Publish when the content changes, not on a timer.
429 artifact_publish_limit A hosted agent's run published its 5 versions.
409 artifact_several_files A hosted agent tried to update a page made of several files. Its owner updates it with lhbox artifact publish <folder>.
403 public_artifacts_not_enabled Public pages are not turned on for the organisation.
400 confirmation_required Making the page public would make a private catalog public. Send its name in confirm_catalogs; the answer lists what is missing.
409 artifact_public_private_data A public page reads public catalogs only. Name public catalogs, or have the owner make the page private first.
403 artifact_public_blocked We took the page off the web. It cannot be made public again until that is lifted.
403 address_not_verified The owner's address is not verified yet.
403 artifacts_not_allowed The hosted agent's definition does not have artifacts. Whoever manages it turns it on.
400 update_has_link An update links only to its own page (page_url in the answer, with an optional #s= place). Say anything else in words; see how an update looks.
http_499 with no message from an upload The connection closed before an answer came: a timeout or a reset on the way. On a CI runner whose uploads hang, run sudo sysctl -w net.ipv4.tcp_mtu_probing=1 on the runner first, then publish again.

Numbers and dates

limit value
page files .html .css .js .json .geojson .csv .svg, at most 2 MB each
assets .png .jpg .jpeg .webp .gif .avif .woff2 .parquet .pmtiles .mp4, at most 20 MB each
one version at most 25 MB and 200 files
catalogs a page names at most 20
versions kept the newest 20
a note cut at 200 characters
publishing 30 versions an hour for each key; a hosted agent's run 5
reading a page's files back 60 an hour for each key
artifacts in an organisation 200
a deleted artifact in the trash, restorable for 30 days
lhbox.download 25 MB a file
lhbox.copy 1 MB of text
lhbox.setState 2,000 characters

Measured on 12 November 2026 on DuckDB 1.5.6, in Chromium and WebKit: loading the engine's time-zone support adds about 0.1 s to the first query and 1.6 MB to the first open in a browser. On 2.0.0 it is about 0.04 s and 0.7 MB (13 November 2026).