Give every agent task its own database with Hotdata and Tenki

Agents doing data work need somewhere to put the data. An agent asked to reconcile two exports, profile a dataset or answer a question about last month's orders ends up holding a few files and a lot of intermediate results, and it wants SQL over them. Point it at your shared warehouse and you hand a model write access to production tables and a cleanup job for every run that dies halfway. Give it nothing and it writes pandas in a loop.

A Tenki Sandbox gives the agent an isolated Linux VM to run in. Hotdata gives it a database to match: an instant database is created in one call, filled by loading CSV, JSON or Parquet files, queried with SQL, and deleted, or left to expire on its own. This post covers what that pairing is good for and how to get an agent working with it in a few minutes.

How the work splits

Tenki's public tenki/hotdata:stable image is the standard base image plus the Hotdata CLI, the Python SDK with Arrow support, Hotdata's agent skill and a hotdata-smoke command. It has no API key and no data. Your agent and the client run in the sandbox; storage and the query engine run at Hotdata.

That split decides what each side is good for. The sandbox is where the agent can run anything (shell commands, scripts, the coding agents on the base image) without touching your machine or your other sessions. Hotdata is where the data lives for as long as the task needs it. A database created with expires_at cleans up after the run that never got to its finally block, and a fork gives the agent a copy of a dataset it can change without touching the original. The SQL engine is Hotdata's: queries don't use the sandbox's CPU or memory, so the size of the VM doesn't cap the size of a query.

What agents use it for

A few patterns come up once each task has its own database:

• Scratch space for one task. The agent loads the exports, logs or CSVs it was handed, runs as many SQL queries as the task needs, and the database expires when the task is done, whether or not the agent got to clean up.
• Reference data without copies. Attach a curated database's catalog to the task's database, read-only, and the agent can join its own files against your reference tables without being able to change them.
• Try a change on a fork. Fork a database and let the agent rewrite, dedupe or backfill the fork. The original stays as it was until you decide what to keep.
• Results that outlive the sandbox. When a sandbox ends, its VM goes with it. A database keeps the results for another agent, a dashboard or a person to query later, until its expiry or until you delete it.
• Many sandboxes, one dataset. Several sandboxes can work on the same database at once, each loading its own tables, while any of them queries the combined result with SQL.

The short path

Create an API key in the Hotdata dashboard, export it in your local shell, and pass it to the session and nowhere else. The SDK also needs the workspace ID, which hotdata workspaces list prints:

export HOTDATA_API_KEY=<your-hotdata-api-key>
export HOTDATA_WORKSPACE=<your-workspace-id>

tenki sandbox create \
  --image tenki/hotdata:stable \
  --env "HOTDATA_API_KEY=$HOTDATA_API_KEY" \
  --env "HOTDATA_WORKSPACE=$HOTDATA_WORKSPACE" \
  --name hotdata-demo

Then check the whole path before you write any code:

tenki sandbox exec --session hotdata-demo -- hotdata-smoke

hotdata-smoke creates a database that expires in an hour, loads a CSV into it with the CLI, reads it back through the SDK and the CLI, and deletes it. If it prints the row count back, the key, the workspace and the network path all work.

From there, a task's database is three commands:

db=$(hotdata databases create --name agent-task --table orders --expires-at 2h -o json | jq -r .id)
hotdata databases tables load orders --database "$db" --file orders.csv
hotdata query "SELECT customer, sum(amount) AS total FROM default.public.orders GROUP BY customer" -d "$db"

The Hotdata docs page has the same flow in Python, including uploads of large files and reading results as Arrow tables.

The image also installs Hotdata's agent skill, matched to the pinned CLI, in ~/.claude/skills and ~/.agents/skills. Claude Code, and other agents that read those directories, load it and learn the CLI's commands from it, so a prompt can describe the task (load these exports into a database that expires in two hours, then find the rows that disagree) instead of spelling out the commands.

Keep the key out of images, templates and snapshots

Whoever holds a read-write Hotdata key can read and change every database in the workspaces it reaches. Anything baked into an image is available to every session launched from it, template env values show up in read APIs, and a snapshot of a session that has the key brings the key back in every session restored from it. Pass HOTDATA_API_KEY with --env when the session is created, keep the session short with --max-duration, and give it the narrowest key that works: Hotdata keys can be read-only and limited to specific workspaces.

Pin an exact build

tenki/hotdata:stable moves to each newly published build, and with it the CLI and SDK versions. For an agent you've tested and deployed, resolve the tag once and launch the snapshot it points to:

tenki sandbox registry resolve tenki/hotdata:stable
# image_id    : <image-id>
# snapshot_id : <snapshot-id>

tenki sandbox create --image tenki/hotdata@<snapshot-id>

A snapshot reference never moves. Move to a newer build on purpose, after hotdata-smoke and your own tests pass on it.

Next step

Start with the Hotdata docs page: create a session from tenki/hotdata:stable, run hotdata-smoke, then give your agent a database of its own.