For agents · the instructions your agent follows. The page for people: Start with your agent ←

Quickstart (CLI)

From an email address to a queryable Apache Iceberg catalog in a few minutes, from the terminal or from an agent. Everything here works against https://api.lakehousebox.com today; nothing is described that the service does not do.

What you get

A catalog is one Iceberg REST catalog with its own object storage, run in Nuremberg, Germany, by Lakehousebox, S.L.: it organises your tables and connects them to your tools; LakehouseBox includes the storage and the table maintenance. You bring the engine: DuckDB, PyIceberg or Spark read and write it directly; LakehouseBox is never in your engine's query path (a small, capped server-side query, lhbox query, exists for a quick look). Credentials are per catalog, storage sessions are per table and short-lived, and every tenant is separated at the catalog. (The API calls a catalog a warehouse: /v1/warehouses, warehouse_id; the CLI accepts both words.) The free plan meters one thing, storage: 5 GB. No card.

Everything the service does today, on one page: Capabilities.

1. Install the command line

One Python file, standard library only, verified against a published SHA-256. Python 3.9 or newer. No sudo.

curl -fsSL https://lakehousebox.com/install.sh | sh
lhbox --version

The installer is the only way to get the CLI today: the lakehousebox and lhbox packages on PyPI are name reservations (0.0.1), not the CLI. The installer puts lhbox in ~/.local/bin and prints a PATH hint if that directory is not on your PATH. The CLI talks to https://api.lakehousebox.com by default; set LHBOX_URL only for a self-hosted or local stack. Details: CLI reference.

2. Connect this machine

One command. The CLI prints a link and a code and waits; open the link, create your account there if you have none (name, email, organisation, a password from the mail), accept the Terms, and approve the connection: this machine's name and the catalog. Read is preselected: tick write if the machine must create tables or load data (an agent setting things up for you needs it). The CLI receives its own key, saves it to ~/.config/lhbox/credentials.json (mode 0600) and never shows it. Every later command reads it from there; revoke it any time from your account page. The CLI talks to https://api.lakehousebox.com by default; set LHBOX_URL only for a self-hosted or local stack.

lhbox login
# Open https://lakehousebox.com/app/device?user_code=XXXX-XXXX and approve the connection …
# Connected to demo_data (read and write) as laptop. Saved to ~/.config/lhbox/credentials.json.

Without a browser on this machine, the email-code path still works: lhbox signup --email you@company.com --workspace acme, then lhbox signup --email … --code 123456 --accept-terms --save (six digits by mail from no-reply@lakehousebox.com, valid ten minutes). It ends the way lhbox login does: this machine is connected with its own key (read and write on your first catalog), never a key that acts as you; your account has no password yet, so open Forgot your password? to reach the account page. Your first catalog is named demo_data; another is lhbox catalog create <name> (a minute or so; names match ^[a-z][a-z0-9_]{0,62}$). Every command that names a catalog takes the name (or the id) as its positional argument, --catalog <name> as an alias; the destructive ones (catalog delete, catalog publish) also want --confirm (or --yes). Global flags (--json, --human, --url, --api-key) may go before or after the subcommand.

3. Connect your engine

lhbox connect --engine duckdb                    # or pyiceberg, spark, trino, polars, clickhouse, snowflake; --catalog <name> when you have several

Prints a paste-ready recipe; the catalog's secret is shown as ******** unless you add --show-secrets (pipe it straight into the engine, lhbox connect --show-secrets --human | duckdb, rather than onto your screen; lhbox duckdb does it for you). For DuckDB it is four statements; the one that matters is ATTACH 'acme--demo-data' AS demo_data (TYPE ICEBERG, …) with the bare bucket name, <handle>--<catalog> with underscores as hyphens: the s3:// form attaches read-only. The catalog is attached under its own name, so the recipes of two catalogs paste into one session without colliding, and the recipe's example query is a comment so the block pastes whole. Engines exchange the credential for catalog tokens (an hour) and per-table storage sessions themselves. All three recipes and their gotchas: Engines.

4. Load and query

CREATE TABLE demo_data.demo.cities AS SELECT * FROM read_parquet('cities.parquet');
SELECT country, count(*) FROM demo_data.demo.cities GROUP BY 1 ORDER BY 2 DESC;

That is an Iceberg table now: versioned, maintained by the catalog (compacted when it is format-version 2, the default), readable by any engine pointed at the catalog. Many files, or CSV files, in one commit: lhbox table import 'data/*.parquet' --namespace demo --name cities (Engines). To choose identifier fields, required columns or partitioning, create the table first with lhbox table create --column id:long:required:identifier … and then INSERT. Check what landed with lhbox table get --catalog demo_data --namespace demo --name cities.

5. Give agents their own keys

lhbox token create --name reporter --grant <warehouse_id>:write
# Token reporter created (member of the organisation; grants: demo_data:write). Its API key, shown once: al_live_…

A token holds exactly the grants you give it, read or write per catalog (none until granted), is revoked on its own (lhbox token revoke <name>) and never manages the organisation or its people. Invite colleagues with lhbox org invite --email …; claim your company's email domain with lhbox org domain --domain … so verified colleagues can join.

For agents

Output is JSON whenever stdout is not a terminal; every error is a typed object with a code, a message and usually a remedy; the exit code carries the class (1 fix the input, 2 a real limit or conflict, 3 auth, 4 not found, 5 retry, 6 malformed command). lhbox usage (GET /v1/usage) lists every limit with its headroom so a limit is never met by failing. Every mutation takes --idempotency-key. The whole documentation as one plain-text file: /llms-full.txt; the index: /llms.txt.

Limits on the free plan

Storage is the store's own figure for your buckets, read every few minutes and summed over the organisation (Iceberg metadata files are not counted, so a catalog can go a little over); over the limit, creating catalogs or tables and vending write credentials answer 409 quota_exceeded (reading still works) until space is freed. The guidelines are abuse limits, not prices, and nothing refuses the next file today; GET /v1/usage returns every limit with enforced: true|false and how (limits_detail). Paid plans are to be announced.

Fair use of egress. Reading your data out is not charged: engines and agents reading and querying your tables, copying your own data out, and others reading a catalog you publish as a public dataset are what it is for. Serving files to the public as a CDN or download host, hot-linking objects from websites or apps, or egress far out of proportion to what you store is not covered; the level we look at is monthly egress above about three times the organisation's stored bytes. The store counts the bytes sent out of each bucket, and GET /v1/usage shows them per catalog per day (bytes_out). Above that level we contact you first; only if it continues do we restrict or suspend that traffic (by revoking the credentials that carry it or withdrawing a catalog's public access). We never delete data for it. The terms: Acceptable use, section 4.

Not available today

• A Snowflake data path on every Snowflake account: Snowflake reads the tables only on an account where Snowflake Support has allowed s3.lakehousebox.com (a support case per account, see Engines).
• Sign in with Google or any social login; accounts are created with your email address (a password set from the signup mail in the browser, a six-digit code in the CLI). A self-hosted deployment may trust its own OpenID Connect issuer instead.
• A full web dashboard. There is /app/, "Your account" (small, for people; agents use the API): log in with email and password (the session stays in the tab), see the organisation's catalogs with your level on each, create one, delete one by typing its name, create tokens for agents with read or write per catalog (the key is shown once), invite and manage members, read usage against the 5 GB, and run SQL with DuckDB compiled to WebAssembly in the browser (the site never sees the data; it talks to the catalog and the object store with your own scoped credentials). It refuses writes as a courtesy, not as a permission; the API and the CLI remain the primary interface.
• An SLA; we publish what we measure instead. One site, hourly off-host backups with a second copy in Helsinki, a restore drilled weekly.
• Paid plans (waiting for the company registration).

Help

hello@lakehousebox.com. Security reports: the same address (security.txt). Legal: Terms, Privacy, Acceptable use, Data processing, Security overview, Legal notice.