# SQLite

> Source: `src/content/docs/agent-os/sqlite.mdx`
> Canonical URL: https://rivet.dev/docs/agent-os/sqlite
> Description: Give agents access to a persistent SQLite database via host tools.

---
Each agentOS actor has a built-in SQLite database that persists across sessions and sleep/wake cycles. Expose it to agents as a host tool so they can run arbitrary SQL queries.

## Example

Give the agent a single `sql` tool that executes any SQL query against the actor's SQLite database.

```ts @nocheck
import { agentOs } from "rivetkit/agent-os";
import { setup } from "rivetkit";
import common from "@rivet-dev/agent-os-common";
import pi from "@rivet-dev/agent-os-pi";
import { db } from "rivetkit/db";
import { toolKit, hostTool } from "@rivet-dev/agent-os-core";
import { z } from "zod";

const actorDb = db({});

const sqlToolkit = toolKit({
  name: "db",
  description: "SQLite database",
  tools: {
    sql: hostTool({
      description: "Execute a SQL query against the actor's SQLite database. Use this for creating tables, inserting data, and querying data. Returns rows for SELECT queries.",
      inputSchema: z.object({
        query: z.string().describe("SQL query to execute"),
      }),
      execute: async (input) => {
        const result = await actorDb.execute(input.query);
        return result;
      },
    }),
  },
});

const vm = agentOs({
  db: actorDb,
  options: { software: [common, pi], toolKits: [sqlToolkit] },
});

export const registry = setup({ use: { vm } });
registry.start();
```

The agent calls it as a CLI command:

```bash
agentos-db sql --query "CREATE TABLE notes (id INTEGER PRIMARY KEY, content TEXT, created_at INTEGER)"
agentos-db sql --query "INSERT INTO notes (content, created_at) VALUES ('auth uses JWT with 24h expiry', 1711843200000)"
agentos-db sql --query "SELECT * FROM notes WHERE content LIKE '%auth%'"
```

The database persists in the actor's storage across sessions and sleep/wake cycles. The agent can create whatever schema it needs and build up structured data over time.

## Recommendations

- See [SQLite](/docs/actors/sqlite) for the full SQLite API reference.
- See [Tools](/docs/agent-os/tools) for how host tools work.

_Source doc path: /docs/agent-os/sqlite_