Persistent analytical data for agents.

The agent installs the CLI and runs lhbox login. The CLI prints a link with a code, opens the browser when there is one, and waits up to fifteen minutes; the agent shows the person the link. --level read asks for read only, --name names the connection, --catalog picks one; the default is the organisation's default catalog with read and write.

$ curl -fsSL https://lakehousebox.com/install.sh | sh
$ lhbox login
# Open https://lakehousebox.com/app/device?user_code=XXXX-XXXX
# and approve the connection in your browser (code XXXX-XXXX).
# … waiting (up to 15 minutes)

The person opens the link. With no account yet, the same page offers to create one: name, email, organisation, the link in the mail, a password, and the Terms; the code survives. Then a consent screen names the machine, the catalog and the access asked for, which they may lower to read. On approval the CLI receives the key of a new agent named after the machine, saves it to ~/.config/lhbox/credentials.json and never shows it. Revoke it any time under Connections & tokens. A key can also be minted by hand for a machine without a browser.

# the CLI, once approved:
Connected to demo_data (read and write) as laptop.
Saved to ~/.config/lhbox/credentials.json.
# by hand, from a person's terminal, key shown once:
$ lhbox agent create --name reporter \
    --grant <warehouse_id>:write

Before touching anything, the agent reads its identity, its limits and the tables that exist. Output is JSON whenever stdout is not a terminal, so a script parses the same thing a person reads. GET /v1/usage lists every limit, the current value and the headroom: a limit is never met by failing. The first catalog is demo_data; another is lhbox catalog create --name <name>, where a name matches ^[a-z][a-z0-9_]{0,62}$ (SQL-friendly; anything else is 400 invalid_name with a suggestion).

$ lhbox whoami
# who am I, my limits, what I hold on each catalog
$ lhbox usage
# enforced: storage 5 GB, catalogs 3/project, snapshot history 20 · 7 days
# guidelines (limits_detail.enforced = false): tables 50, namespaces 10,
# objects 50,000, commits 20,000/month, 10 s between commits
$ lhbox table list --catalog demo_data
$ lhbox table get --catalog demo_data --namespace demo --name cities
# schema, format version, snapshots, rows, data_files

One command returns the paste-ready SQL for the agent's DuckDB (1.5.5 or newer), with the catalog's credential inside. The engine exchanges it for catalog tokens (900 s) and per-table storage sessions itself. ATTACH the bare bucket name, <handle>--<catalog> with underscores as hyphens: 'acme--demo-data' is read-write, the s3:// form attaches read-only. The recipe's fourth statement, an S3 secret for inspecting the bucket, is not needed for tables. Shorter: lhbox duckdb opens the DuckDB shell already attached, the recipe passing through a private file it deletes a second later; --persist writes DuckDB persistent secrets instead, so any later session needs only the ATTACH line. Single-stream throughput depends on your network path: inside Hetzner's network about 470 MB/s per stream, from a laptop in Madrid 39 MB/s on one stream (measured 2026-09-21), and DuckDB reads Parquet row groups in parallel by itself.

$ lhbox connect --catalog demo_data --engine duckdb
INSTALL iceberg; LOAD iceberg; INSTALL httpfs; LOAD httpfs;
CREATE SECRET lhbox (TYPE ICEBERG,
  CLIENT_ID '<client_id>', CLIENT_SECRET '<client_secret>',
  OAUTH2_SERVER_URI 'https://catalog.lakehousebox.com/v1/oauth/tokens');
ATTACH 'acme--demo-data' AS demo_data (TYPE ICEBERG,
  ENDPOINT 'https://catalog.lakehousebox.com', SECRET lhbox);

Importing Parquet is one statement, from a local file or a URL; namespaces are schemas. Measured against the service: a million rows, 18 MB of Parquet, in about 2.3 s from a laptop, three data files, one commit. Many files at once: lhbox table import --namespace demo --name events data/*.parquet makes one commit however many files (44 files one by one were 44 commits and 44 waits), keeps GeoParquet metadata as table properties, and creates a format-version 3 table with typed geometry when the catalog's default asks for it.

-- a new table, from a file or a URL
CREATE TABLE demo_data.demo.events AS
  SELECT * FROM read_parquet('events.parquet');
-- into a table that exists
INSERT INTO demo_data.demo.events
  SELECT * FROM read_parquet('more-events.parquet');
COPY demo_data.demo.events FROM 'more-events.parquet' (FORMAT PARQUET);
-- namespaces are schemas
CREATE SCHEMA demo_data.staging;

From here on it is DuckDB. The engine lists the table through the catalog, receives storage credentials scoped to that table, and reads the Parquet files from s3.lakehousebox.com itself. LakehouseBox sees the catalog call and the object reads; it never sees a result set.

SELECT date_trunc('day', event_time) AS day,
       count(*) AS events,
       avg(value) AS mean_value
FROM demo_data.demo.events
GROUP BY 1 ORDER BY 1;

A saved result is a table another session can open. One CTAS and the summary lives next to the source, versioned and maintained like it. CTAS makes every column optional; when identifier fields, required columns or partitioning matter, create the table first with lhbox table create --column name:type[:required][:identifier], then INSERT.

CREATE TABLE demo_data.demo.daily_summary AS
  SELECT date_trunc('day', event_time) AS day,
         count(*) AS events, avg(value) AS mean_value
  FROM demo_data.demo.events GROUP BY 1;

-- a later session, another agent, a colleague:
SELECT * FROM demo_data.demo.daily_summary ORDER BY day DESC LIMIT 7;

Access is a grant per catalog: read or write, to a member or to an agent key. A read holder's connect carries the read-only identity; the catalog refuses its commits and the store its writes. Colleagues join by invitation, or automatically once your organisation has claimed its email domain.

$ lhbox org invite --email colleague@company.com --role member
# the invitation token is returned once and mailed
$ lhbox catalog grant --catalog demo_data \
    --principal <principal_id> --level read
$ lhbox agent create --name analyst --grant <warehouse_id>:read
$ lhbox catalog grants --catalog demo_data
# who holds read or write, and how: admin, membership, creator, grant

A person's lost key is replaced by a code to their email, never recovered; an agent's lost key is revoked and a new agent created. The audit log answers who did what, for 400 days. Snapshot history is bounded: maintenance keeps 20 snapshots and 7 days per table, so time travel reaches back that far and no further.

$ lhbox recover --email you@company.com
$ lhbox recover --email you@company.com --code 123456 --save
# a NEW key; earlier keys keep working until revoked
$ lhbox agent revoke --agent-id <agent_id>
# every key of that agent stops at once
$ lhbox audit --since 7d --action credentials.vend
$ lhbox catalog rotate --catalog demo_data
# new catalog credentials; old tokens refused now, vended
# storage sessions run out within about an hour; fetch a fresh recipe