Quickstart (CLI)

From an email address to an Apache Iceberg catalog you can query, in a few minutes, from the terminal or from an agent. Everything here works against https://api.lakehousebox.com today.

curl -fsSL https://lakehousebox.com/install.sh | sh     # the lhbox CLI
lhbox login                                       # opens your browser; you click Allow
lhbox connect --engine duckdb                     # the attach recipe for your engine
lhbox duckdb                                      # or: DuckDB with the catalog already attached

What you get

A catalog is an Iceberg REST catalog with its own storage, run in Frankfurt, Germany, by Lakehousebox, S.L. It holds your tables; LakehouseBox stores them and maintains them. You bring the engine: DuckDB, PyIceberg, Spark, Trino, Polars and Snowflake read and write it, and ClickHouse reads it (Engines has each one's status). LakehouseBox is never in your engine's query path. For a quick look without an engine, lhbox query runs a small, capped query on our side.

Each catalog has its own credentials, 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. How it all fits: How it works.

Install the command line

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

One Python file, standard library only, checked against a published SHA-256. It needs Python 3.9 or newer and no sudo, and goes into ~/.local/bin; the installer prints a hint when that is not on your PATH. The installer is the only way to get the CLI: the lakehousebox and lhbox packages on PyPI are name reservations. The CLI talks to https://api.lakehousebox.com; set LHBOX_URL only for a self-hosted or local stack. More: CLI reference.

Connect this machine

lhbox login
# Opening your browser to sign in. If it does not open, open this link on THIS computer: …
# Connected to acme_corp (read and write) as laptop. Saved to ~/.config/lhbox/credentials.json.

Your browser opens the account page; sign in if needed and click Allow, and the browser comes back to this machine. Without a browser here (an SSH session, a server), or with --no-browser, the CLI prints a link with its code instead: open it anywhere, check the request and approve it. With no account yet, create one first: name, email, organisation, then a password from the mail. Accept the Terms and allow it. A login is yes or no: there is no catalog or level to pick.

The CLI receives a key that acts as you: it can do what you can do on the website, in every organisation you belong to, for 30 days; then run lhbox login again. It saves the key to ~/.config/lhbox/credentials.json (mode 0600), never shows it, and every later command reads it from there. You can revoke it on your account page (Settings › Access keys) at any time.

Your first catalog is named after your organisation's handle, with underscores for dashes: handle acme-corp, catalog acme_corp. The examples below use it. Make another with lhbox catalog create <name>, usually in seconds; names match ^[a-z][a-z0-9_]{0,62}$.

No account, or nobody to approve right now? lhbox new gives this machine a catalog it can write at once, with no account: 1 GB, nothing public. A person keeps it with lhbox claim; otherwise it is deleted with its data after 72 hours. Running it accepts the Terms for whoever runs it. The recipe: /new; the details: Agent setup, "Without an account".

No browser on this machine? Sign up by email code instead: lhbox signup --email you@company.com --workspace acme, then lhbox signup --email … --code 123456 --accept-terms --save. The six digits come by mail from no-reply@lakehousebox.com and last ten minutes. The machine ends up connected with a key of its own: a token of your organisation with read and write on your first catalog (unlike lhbox login, whose key acts as you). Your account has no password yet: use Forgot your password? to reach the account page.

Connect your engine

lhbox connect --engine duckdb                    # or pyiceberg, spark, trino, polars, clickhouse, snowflake

This prints a recipe to paste into your engine. Add --catalog <name> when you have several catalogs. The catalog's secret shows as ********. To use it without putting it on your screen, pipe it into the engine: lhbox connect --show-secrets --human | duckdb, or let lhbox duckdb do it.

For DuckDB the recipe is four statements. The one that matters is ATTACH 'acme-corp--acme-corp' AS acme_corp (TYPE ICEBERG, …), with the bare bucket name <handle>--<catalog>: the s3:// form attaches read-only. Each catalog attaches under its own name, so two recipes paste into one session. Engines swap the credential for catalog tokens and per-table storage sessions, each about an hour, by themselves. Every recipe and its gotchas: Engines.

Load and query

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

That is an Iceberg table now. It is versioned, maintained by the catalog (compacted, old snapshots expired) and readable by any engine pointed at the catalog.

Many files, or CSV files, in one commit: lhbox table import demo.cities 'data/*.parquet' (Importing files). To set identifier fields, required columns or partitioning, create the table first with lhbox table create acme_corp.demo.cities --column id:long:required:identifier …, then INSERT. Check what landed with lhbox table get acme_corp.demo.cities.

Give agents their own keys

lhbox token create --name reporter --grant <warehouse_id>:write
# Token reporter created (member of the organisation; grants: acme_corp: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. It is revoked on its own with lhbox token revoke <name>. It is a member of the organisation, so it does not manage the organisation or its people, unless you create it with --role admin (capped by your own role). 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 gives 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 you never have to meet one by failing.

The commands that create something (project create, catalog create, table create, table import) take --idempotency-key, so a retry after a timeout never makes a second one. Where to start reading: /llms.txt; everything in one file: /llms-full.txt.

Limits on the free plan

whatvalueenforced
storage, private · public5 GB · 5 GByes: the one metered thing; bucket quota, and 409 at create and vend time
catalogs per project · projects per account10 · 5yes, at creation
tables · namespacesno limit—
objects50,000no: guideline, metered every few minutes (approximately); the cost driver, compaction keeps it down
catalog operations · commits per month · seconds between commits1,000,000 · 20,000 · 10no: guideline
snapshot retention20 snapshots · 7 daysapplied by maintenance, not disableable
server-side queries (POST /v1/query, MCP): seconds per query · rows · running per organisation · in flight per key · requests a second per key20 s · 2,000 · 4 · 4 · 5yes: no quota, one queue every tenant shares; 408 query_timeout, 429 busy or 429 rate_limited with retry_after_seconds
egress (bytes read out of your buckets)free; fair use up to about 3× what the organisation stores, per monthno: guideline, counted per catalog per day (bytes_out in each day of traffic, GET /v1/usage); above it we contact you first (fair use)

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 until space is freed; reading still works. 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 storage is set at €0.10 per GB-month of private storage above the free 5 GB, from the day paid plans open.

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 and writes the tables only on an account where Snowflake Support has allowed s3.lakehousebox.com (a support case per account, see Engines).
  • An SLA; we publish what we measure instead. One site; the stored data replicated from Frankfurt, Germany, to Stockholm, Sweden, the catalog's state backed up every 5 minutes.
  • Paid storage: €0.10 per GB-month above the free 5 GB, not open yet. Until it opens, write to hello@lakehousebox.com and we raise a limit, free.

Help

What an error means and what to do: Errors and help. Whether the service is up: status.lakehousebox.com. hello@lakehousebox.com. Security reports: the same address (security.txt). Legal: Terms, Privacy, Acceptable use, Data processing, Security overview, Legal notice.