Actor Runtime Socket

Access an actor's SQLite database from another local process.

The Actor Runtime Socket is an advanced Beta API for integrating Rivet Actors with external software without sacrificing performance. It currently exposes SQLite over Unix domain sockets in the native runtime.

For example, an agentOS agent can use the socket to work with its actor’s SQLite database. Software orchestrated by an actor, such as another process or container, can use it to access the actor’s runtime resources. Like the Chrome DevTools Protocol exposes a browser to external tools, the Actor Runtime Socket exposes selected actor capabilities to colocated software.

Quickstart

Enable the socket, call c.actorRuntimeSocket() to get its path, and pass that path to your process:

import { spawn } from "node:child_process";
import { actor } from "rivetkit";
import { db } from "rivetkit/db";

export const example = actor({
  options: { enableActorRuntimeSocket: true },
  db: db({
    onMigrate: (db) =>
      db.execute("CREATE TABLE IF NOT EXISTS items (value TEXT)"),
  }),
  actions: {
    startWorker: async (c) => {
      // Get the Unix socket path external processes use
      // to communicate with the actor.
      // (Example: /tmp/rivet-actor-runtime.abc/def.sock)
      const { path } = await c.actorRuntimeSocket();

      // Spawn a process that can access the actor's
      // SQLite database over the socket.
      spawn(process.execPath, ["worker.js"], {
        env: { ...process.env, ACTOR_RUNTIME_SOCKET_PATH: path },
      });
    },
  },
});

import { connectRuntimeSocket } from "./generated/runtime-socket-client";

const db = await connectRuntimeSocket(process.env.ACTOR_RUNTIME_SOCKET_PATH!);
const rows = await db.query("SELECT value FROM items", []);
console.log(rows);

The path is valid only for the current actor generation, so get it again after the actor restarts or wakes. Only share it with trusted local processes.

Protocol

The protocol schema defines the handshake, SQLite requests, values, responses, and errors. Generate codecs using vbare’s TypeScript or Rust tooling, then add a small Unix socket wrapper for its length-prefixed frames. connectRuntimeSocket above represents that application-specific wrapper.

SQLite transaction interleaving

Separate socket requests can interleave with SQLite work from the main actor. For multi-request atomic work, begin a transaction with a client-generated leaseKey, include that key with each query, and commit or roll back with the same key. Other actor and socket SQL waits until that transaction finishes.