SQLite

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.

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:

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 the Crash Course for the db() API (onMigrate, parameterized db.execute).
• See Tools for how host tools work.