Agent setup

Written for the agent, not the person: paste https://tablemere.com/docs/agent-setup/ into your agent, or use the prompt on the agents page. The person's part is to approve the connection once in the browser. Source: the repository note docs/agent-setup.md.

You are an agent setting up Tablemere for a person. Follow these steps in order. The person authorises access once, in their browser; you do the rest. Never print, paste or store a credential in the conversation: the CLI saves the key it receives to ~/.config/tablemere/credentials.json and every later command reads it from there.

Tablemere is a managed Apache Iceberg lakehouse operated in Europe: one catalog per organisation to start (an Iceberg REST catalog with its own storage; the hierarchy is organisation -> catalog -> namespace -> table), and DuckDB as the engine you run locally. The API calls a catalog a warehouse (/v1/warehouses, warehouse_id); the CLI says catalog and accepts warehouse too. API: https://api.tablemere.eu. Site and docs: https://tablemere.com.

1. Install the CLI

curl -fsSL https://tablemere.com/install.sh | sh       # a single Python 3 file, no dependencies
tablemere --version

Or, if the person prefers a package manager: pipx install tablemere or pip install --user tablemere. The CLI needs Python 3.10 or newer, which macOS and every current Linux ship.

2. Connect this machine

tablemere login

What happens:

  1. The CLI prints a link (https://tablemere.com/app/device?user_code=XXXX-XXXX) and the code, opens the browser when there is one, and waits (up to 15 minutes).
  2. Tell the person: "Open this link and approve the connection in your browser" (repeat the code in case the link does not open). If they have no account yet, the same page offers Create your account: they fill in their name, email and organisation, click the link in the mail, choose a password, and land back on the approval with the code intact. Nothing else is needed from them.
  3. The person sees a consent screen: this machine's name, the catalog, and the access asked for (read and write by default; they may lower it to read only). They approve.
  4. The CLI receives the key of a new agent of their organisation, named after this machine and holding exactly the approved access, saves it, and prints: Connected to My catalog (read and write) as <machine>. Saved to ~/.config/tablemere/credentials.json.

The key is never shown. Do not ask for it, do not look for it, do not cat the credentials file. Every tablemere command and the connection recipe below read it themselves. If the person wants to see or remove the connection later: their account page, Connections & tokens; revoking it stops this machine at once.

Running tablemere login again on a machine whose saved key still works answers Still connected … and starts nothing new. --level read asks for read only; --name <agent> names the agent; --new forces a fresh authorisation.

If the code expired before the person approved (15 minutes), run tablemere login again and send the new link.

3. Get the DuckDB recipe

tablemere whoami                          # kind: agent, my_level on the catalog
tablemere connect --engine duckdb         # a paste-ready DuckDB recipe for the connected catalog

connect prints the SQL to attach the catalog: its REST endpoint, the storage endpoint, and a short-lived credential it fetched for you. Run that SQL in DuckDB (pip install duckdb, or the duckdb binary). Do not copy the credential anywhere else; re-run tablemere connect when it expires.

4. Check that DuckDB can read and write

Attach with the bare bucket name the recipe gives (ATTACH 'w-<uuid>' AS lake (TYPE iceberg, …)), never s3://w-<uuid>/ -- the s3:// form attaches read-only in DuckDB and every INSERT then fails with "attached in read-only mode". Then:

SHOW ALL TABLES;                                             -- one SELECT against the catalog
CREATE SCHEMA IF NOT EXISTS lake.scratch;
CREATE TABLE lake.scratch.setup_check AS SELECT 1 AS ok, now() AS at;
SELECT * FROM lake.scratch.setup_check;                      -- one INSERT read back
DROP TABLE lake.scratch.setup_check;

If the CREATE fails with a 403 or AccessDenied, the connection is read only (the person lowered it, or holds read themselves). Say so; a person with write can grant it from the account page.

5. The first task

Do what the person asked. The three common starts:

  • Use their files: CREATE TABLE lake.<schema>.<name> AS SELECT * FROM read_csv('path') (or read_parquet). One statement per file; Iceberg tables, partitioning optional. Then answer their question with SQL.
  • Try an example dataset: DuckDB reads public Parquet over HTTPS; load one into a table the same way and show a few queries.
  • Continue an existing project: SHOW ALL TABLES, describe what is there, and pick up from it.

tablemere table list --catalog <id> and tablemere table get show tables, schemas and row counts from the API side; tablemere usage shows the free tier (5 GB) and headroom.

Agent environment: getting started

Your environment Start with
You can execute commands and run DuckDB (Claude Code, Codex, a shell tool) Steps 1–5 above: the CLI connection, then local analysis with DuckDB. Everything the person needs to do is approve once in the browser.
MCP only, no shell (Claude Desktop with the Tablemere MCP server, no code execution) Ask the person to run tablemere login and tablemere mcp install --client claude-desktop once in a terminal; the server then exposes the account as tools: list catalogs, connection recipes and short-lived table credentials, grants, tokens, members, usage, audit. Missing for analysis: the MCP server runs no queries -- there is no query tool -- so loading files or answering questions over the data needs an engine you can run. Say so, and offer the CLI path. docs/mcp.md has the tool list.

Rules

  • Credentials stay out of the conversation. The CLI saves them; --show-key exists for a person who asks, not for you.
  • One connection per machine; revoke from the account page, never by deleting the file (the agent would stay valid).
  • Everything is in the open formats it says: Iceberg tables in an S3 bucket the person can take elsewhere.