For agents · the instructions your agent follows. The page for people: Agents that run on a schedule
Hosted agents: a prompt LakehouseBox runs next to your data
On for every organisation: up to three agents, 4 runs a day and 5 million tokens a month on the models we provide, free, and two integrations to act in the tools you use (the limits below). An organisation an agent made without an account gets them once a person claims it.
A hosted agent is a prompt that LakehouseBox runs for you, on demand or on a schedule. It reads the catalogs you choose with SQL and keeps a few values between runs. It can append rows to tables you name, read web hosts you name, email you and the members who subscribe, and use tools of MCP servers you connect. The model runs in the EU (Scaleway, Paris). Your agent brings no compute and holds no key.
Each agent acts through an identity of its own. It reads exactly the catalogs its definition names and nothing else, whoever created it. Only its creator or an admin of the organisation changes those catalogs, with lhbox agent update or with a catalog grant to the agent's identity. Anyone else who holds write on a catalog gets 403 not_agent_manager, because what the agent reads reaches a model that can use its creator's integrations.
The short path
lhbox agent create garden_morning --prompt @prompt.md --catalog garden \
--schedule "0 8 * * *" --tz Europe/Madrid --state-key journal --notify-owner
lhbox agent run garden_morning --dry-run --wait # a test run: see what it would do
lhbox agent run garden_morning --wait # a real run
lhbox agent show garden_morning # its definition, schedule, memory and last run
The account page does the same: Agents, "+ New agent".
lhbox agent update <name> changes any part of an agent. Only what you pass changes, and every change is a new version. --pause and --resume stop and restart its schedule. lhbox agent delete <name> --yes removes it; its runs stay readable.
What an agent can do in a run
| tool | what |
|---|---|
list_tables, describe_table |
the tables of its catalogs, with their columns and docs |
read_catalog_guide |
a catalog's AGENTS.md: your guide to its tables (treated as data, not instructions) |
run_sql |
one read-only DuckDB statement over its catalogs (the same query service as POST /v1/query) |
remember |
keep a small value (up to 2,000 characters) under one of its declared keys, for its next run |
note, resolve, recall, flag_owner |
with memory topics (--topic, up to 12): note observations, alerts and decisions about items, close them when done, read older notes, and flag what only you can decide; each run starts from a short view of what is open and current |
notify_owner |
email you (the person who created it) and its subscribers, at verified addresses, at most once per run and five times a day; the body is Markdown |
publish_artifact, read_artifact, list_artifacts, delete_artifact |
publish a page for people, and the next versions of the pages it keeps (the ones it published or was given, until their owner takes one back), at most five versions a run; delete one of those into the trash, where you restore it for 30 days; Artifacts |
append_rows |
add rows to a table its definition names (--write): append-only, checked against the table's columns |
fetch_url |
GET a page or an API answer from a host its definition names (--allow-host) |
view_image |
look at an image in one of its catalogs' files (only on a model that sees images) |
| integration tools | the tools of connected MCP servers you allow it, by name |
Emails
Members of the organisation can have an agent's notices sent to them too. Each one clicks "Email me this agent's notices" on its page, or runs lhbox agent subscribe <name> (lhbox agent unsubscribe <name> to stop). Each person subscribes only themselves and needs a verified address. They must also be able to read every catalog the agent reads, since a notice can carry what it read. An agent that uses (or once used) someone's integrations or web keys emails only its creator and the organisation's admins, since its notices can carry what those accounts returned.
Every email has its own "Stop emails from this agent" link, and your mail provider's unsubscribe button does the same. On your email as its creator, it turns notify_owner off. Turn it back on from the page or with lhbox agent update <name> --notify-owner. On a subscriber's email, it ends only that person's subscription.
Writing to tables
lhbox agent update <name> --write garden.journal.entries lets the agent append rows there. The table must exist and be in a catalog the agent reads, and you must be able to write there. A table fed by a sink that reshapes rows (a mapping), or by Scheduled SQL, is refused.
Rows are checked against the table's columns. An unknown column, a missing required one or a wrong type is refused, with the row and column to fix. Rows are stored at once and committed to the table within about a minute, the same way as an ingest sink. A retried call is never stored twice. A test run checks the rows and writes none. --no-writes takes the tables away.
Reading the web
lhbox agent update <name> --allow-host api.open-meteo.com lets the agent GET https URLs on that host:
- host names only: no IP addresses, no internal names;
- port 443;
- redirects followed only to hosts it may read;
- at most 2 MB read per page, and 20,000 characters given to the model.
For an API that needs a key, store it once as a web key and name the host it goes to:
lhbox integration add aemet --web-key --host opendata.aemet.es --header api_key --api-key-stdin < key.txt
lhbox agent update garden_morning --host-credential opendata.aemet.es=aemet
The key is sent in that header, to that host only. With --key-param NAME it goes as that query parameter instead. It is never shown to the model, never in a tool's answer and never in a run's record. It is never sent to another host, even on a redirect. --no-web takes the hosts away.
Looking at images
On a model that sees images, view_image shows the agent one image by its key. The image comes from the files of a catalog it reads (the file bucket next to its tables). Find the key first in the table that indexes the files (a camera's images table, say).
The image is downscaled to 1,024 pixels on its long edge, or up to 1,536 if the agent asks. It is sent to the model as part of the run. The run's record keeps its key and size, never the image. A run may look at 6 images, 3 MB together. What is written in a photo is treated as data, never as an instruction.
Not yet
Agents cannot POST to the web or run Python. To bring outside data in on a schedule without a model, use Scheduled SQL.
Models
Every model runs in the EU, on Scaleway in Paris. Choose one on the agent's page or with lhbox agent update <name> --model <model>. lhbox agent models lists them.
| model | sees images | uses your allowance |
|---|---|---|
deepseek-v4-flash (DeepSeek V4 Flash, the default) |
no | ×1 |
qwen3.6-35b (Qwen 3.6 35B) |
yes | ~0.8× as fast |
qwen3.5-397b (Qwen 3.5 397B) |
yes | ~1.9× as fast |
The allowance counts tokens of the default model. A run on another model is charged its input and output tokens, each weighted by that model's price over the default's. The figures above are for a typical run, about 12 % output. A model that writes long answers uses the allowance faster than that: the Qwen models reason before they answer. A run's record shows both its tokens and what it cost the allowance (allowance_tokens).
Schedules
A schedule is a cron line of five fields, evaluated in a time zone, so summer time is handled. It may not run more often than hourly. It may not run more times a day than your organisation's runs per day.
- A run that comes due while the previous one is still going is skipped.
- After downtime, the newest missed run runs once.
- Three scheduled runs failing in a row pause the agent and email you.
- An agent LakehouseBox paused (it kept failing, or you lost access to its catalogs or tables) emails you a reminder after three days, then every week, until you resume it.
- Three scheduled runs in a row that did not start (skipped, or refused because the runs or tokens were used up) email you once, and not again until it runs.
- A scheduled run that ends "needs attention" emails you its final message.
lhbox agent listandGET /v1/agentsshow each agent'shealth:stateisactive,on_demand,paused(by a person),stopped(by LakehouseBox;reasonsays why),failingornot_running, withsince,last_succeeded_atandslots_not_run.
The account page previews the next five runs.
Test runs
lhbox agent run <name> --dry-run runs the agent for real, with a few differences. "Test run" on the page does the same, and so does {"dry_run": true} on POST /v1/agents/{agent}/run.
- Its email and its memory writes are recorded in the run, not performed.
- An integration offers it only its read-only tools.
- It does not count against the organisation's runs per day. It has its own cap per agent. Its tokens do count.
- A paused agent can be tested.
What a run did
lhbox agent runs <name> --detail, GET /v1/agent-runs/{id} and "What it did" on the page show a run's record:
- every tool call in order, such as a
run_sqlcall with its SQL, its outcome and the size of its answer (never the answer's data); - the email it sent, and whether it reached your mail provider:
sentis true once it has, anddeliverysaysemail,queued(being retried),failed(it could not be delivered) ordry_run(a test run, never sent); - its memory before and after.
Runs and memory are visible to whoever may run the agent. That is its creator (a person or a token) and the organisation's admins (people or admin tokens). A member who reads every catalog the agent has ever read also sees its runs, without its memory or its emails (not for an agent that ran before 2 November 2026, or one that read a catalog deleted since).
One exception: an agent that uses, or ever used, your integrations or web keys. Then only people, signed in as themselves, run it by hand and read its runs' output, traces and memory. A token sees that the runs happened and how they ended, not what they said. Scheduled runs are not affected.
Integrations (MCP servers)
Connect an MCP server once for the organisation (two per organisation), then let each agent use the tools you pick:
lhbox integration add linear --mcp https://mcp.linear.app/mcp --wait # opens a sign-in link; approve in the browser
lhbox integration add mytool --mcp https://… --api-key-stdin < key.txt # a server that takes an API key
lhbox agent update garden_morning --integration linear:list_issues,create_issue
The person: opens the sign-in link in a browser where they are signed in to LakehouseBox, and approves.
A server that supports standard MCP sign-in needs no setup on the person's side: LakehouseBox registers itself there. The sign-in link completes only in a browser signed in to LakehouseBox. Credentials are stored encrypted and are never shown or returned. A run gets a short-lived token only for the integrations its agent uses, and can reach only those servers. lhbox integration list, show, reconnect and delete --yes manage them; the account page has the same.
Who may attach them. Only you attach your integrations and web keys to an agent. Only you change an agent that uses them: its prompt, catalogs and tables, and detaching them too. You do it signed in as yourself, on the account page or with the CLI signed in as you (lhbox login, or your own personal key). A token cannot, even one you made: an API token, a key limited to some catalogs or an MCP client.
Attaching shows you the prompt and the tables your accounts will now act on (integration_review). The CLI prints it.
A run reaches your accounts only through a definition you saved yourself. If a token wrote the prompt, approve it explicitly: save the prompt, or run lhbox agent update <name> --confirm-definition. Until then its runs fail with integrations_unavailable and say so. Anyone who manages the agent may still pause or delete it.
Do not give your personal API key to an agent: it counts as you.
When it fails
| what you see | what it means | what to do |
|---|---|---|
403 feature_not_enabled |
an operator turned hosted agents off for this organisation | ask at hello@lakehousebox.com |
409 limit_reached |
the organisation has as many agents as its plan allows (three) | delete one, or ask for more at hello@lakehousebox.com |
integrations_unavailable |
a token wrote the definition of an agent that uses your integrations | save the prompt yourself, or --confirm-definition |
Limits (per organisation, unless said otherwise)
| default | |
|---|---|
| agents | 3 |
| integrations (MCP servers) | 2 |
| tokens (input and output, of the default model) per month | 5,000,000 |
| runs per day (UTC) | 4 |
| test runs per agent per day | 10 |
| one run | 350,000 tokens, 400 s, 15 model requests, 30 tool calls, 6 images (3 MB) |
| appended by one run | 5,000 rows, 5 MB (at most 1,000 rows per call) |
| fetches by one run | 20 |
| web hosts per agent | 10 |
| subscribers per agent | 20 |
| shortest schedule | hourly |
GET /v1/agents shows what is used (lhbox agent list). lhbox agent models lists the models and their price per million tokens. Every route is in the API reference under "Hosted agents".