start using SQLite with your agents
sign up, open a project, and add SQLite to its setup script in settings → server.
sqlite is the lightest database in the catalog and often the most useful one for an agent, because so many projects ship a .sqlite file that nobody can read without the client.
what agents do with it
once the setup script has run, sqlite3 is in the sandbox's path. an agent opens a database with sqlite3 path/to/db.sqlite, uses .tables and .schema to learn its shape, and runs a query in one line when it only needs an answer. for test work it creates a throwaway database, applies the app's schema, and runs the suite against it, all in the conversation's own sandbox.
the matching skill
sqlite ships with a skill of the same name. it carries the three things that save an agent a round trip: how to open or create a database, how to run a one-off query without entering the shell, and how to inspect a schema. skills are versioned documents that load only for the agents you assign them to.
example tasks
- 01
what is actually in the database file the client sent us?
the agent opens it in the conversation's sandbox, lists the tables and their schemas, samples a few rows, and describes the shape rather than opening it in a viewer for you.
bashread - 02
check the migration produces the schema the tests expect.
it creates a fresh database, applies the migration, dumps the schema, and compares it against the fixture the suite loads.
bashgrepedit
what to know before installing
the project needs a sandbox. this is one of the smallest installs there is and depends on nothing else. database files stay in a conversation's sandbox between turns, until the conversation sits quiet for 7 days, and a new conversation's sandbox starts without them.
how to install SQLite
SQLite goes in the project's setup script, not once per team and not on your laptop.
- give the project a sandbox
SQLite runs in each conversation's sandbox, on your team's own sandbox provider account. an owner or admin connects a provider once on the team's providers page, then picks it and a default size for the project, at creation or later in settings → server. a project with no sandbox has nowhere to run it.
- add it to the setup script
settings → server holds the project's setup script, a bash script that runs once on each new sandbox, in /project, with sudo. add SQLite's install commands there and save.
- the next sandbox runs it
the script runs when a conversation's sandbox is created or reused, on the conversation's first turn. settings shows the last run with its exit code and output, and a failed run leaves the sandbox usable rather than blocking the project.
- agents use it through bash
from then on every agent in the project reaches SQLite with the bash tool, on the same filesystem as the checkout they are working in. the conversation's sandbox keeps it between turns, sleeping when idle and waking with the next one.
where SQLite actually lives
each conversation in a project gets its own sandbox on your team's sandbox provider account, and the project's setup script in settings → server decides what is on it. two projects never share a filesystem, so a version pinned for one client cannot collide with another's.
the sandbox provider bills its machine time to your team's account while it runs, and aldena adds nothing. the sizes are on isolated projects, and what agents may run in the sandbox is governed by the project's tool permissions.
faq
what does installing sqlite on a project give the agents?
the sqlite3 command line tool in each conversation's sandbox. agents open or create a database with sqlite3 path/to/db.sqlite, run a one-off query in a single command, and use .tables and .schema inside the shell to inspect a file they have never seen before.
why install anything if sqlite is just a file?
the file is the database, but reading it needs the client. without sqlite3 on the machine an agent can see the bytes and nothing else. with it, the same agent that edits the code can check what the query actually returns.
is there a matching skill?
yes. sqlite ships with a skill of the same name covering opening a database, running one-off queries, and inspecting a schema with .tables and .schema. skills load only for the agents you assign them to.
can an agent work with a database file someone hands it?
yes. a database file checked into the repository or fetched over the network lands in the conversation's sandbox, so the agent can open it with sqlite3 straight away. nothing leaves the project in the process.
spin up your first project.
one project per client, product, or piece of work, staffed with intake, requirements, build and code review agents.
