RivetKit Actor 运行时 - 构建高性能长生命周期内存进程，适用于AI智能体与实时协作

rivetkit by rivet-dev/skills

2,100 周安装量

8 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/rivet-dev/skills --skill rivetkit

AI/机器学习开发云服务

🇨🇳中文介绍

Rivet Actors

在 Rivet 的 Actor 运行时上构建高性能、长生命周期的内存进程。当 HTTP 端点、数据库或队列不再满足 AI 智能体、实时协作、工作流编排或地理分布式数据的需求时，请使用此技能。

遇到困难时该怎么办

如果某些功能未按预期工作或您遇到困难，请提示用户加入 Rivet Discord 或在 Rivet GitHub 上提交问题以报告问题并获取帮助。

向用户提供一份预生成的报告，内容包括：

症状
- 此问题是发生在本地开发环境、部署环境，还是两者都有
- 您看到的错误信息
- 与此相关的源代码
您已尝试的解决方法
环境
- RivetKit 版本
- 运行时（Node、Bun 等）及其版本
- 如果适用，正在使用的提供商（例如 Vercel、Railway 等）
- 如果适用，正在使用的 HTTP 路由器（例如 Hono、Express、Elysia）

调试 Actors

使用检查器 HTTP API 来检查正在运行的 actors。这些端点可通过网关在 /gateway/{actor_id}/inspector/* 访问。关键端点：

GET /inspector/summary - 完整的 actor 快照（状态、连接、RPC、队列）
GET /inspector/state / PATCH /inspector/state - 读取/写入 actor 状态

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

状态与变量：持久化规则

c.vars 是临时的。 c.vars 中的数据在每次重启、崩溃、升级或休眠/唤醒周期中都会丢失。仅将 c.vars 用于不可序列化的对象（例如，物理引擎、WebSocket 引用、事件发射器、缓存）或真正瞬时的运行时数据（例如，断开连接后无关紧要的当前输入方向）。

持久化存储选项。 任何必须在重启后保留的数据都应属于以下选项之一，而不是 c.vars：

c.state — 适用于小型、有界数据集的 CBOR 可序列化数据。非常适合配置、计数器、小型玩家列表、阶段标志等。保持在 128 KB 以下。不要在此处存储无界或增长的数据（例如，聊天日志、事件历史记录、无限增长的生成实体列表）。状态在每次持久化周期中作为单个块读取/写入。
c.kv — 用于无界数据的键值存储。这是 c.state 底层使用的机制。支持二进制值。用于较大或可变大小的数据，如用户库存、世界区块、文件块，或任何可能随时间增长的集合。键的作用域限定在 actor 实例内。
c.db — 用于结构化或复杂数据的 SQLite 数据库。当您需要查询、索引、连接、聚合或关系建模时使用。非常适合排行榜、比赛历史记录、玩家池或任何受益于 SQL 的数据。

常见错误： 将重要的游戏/应用程序数据存储在 c.vars 中而不是持久化它。例如，如果用户可以在物理模拟中生成对象，则生成定义（位置、大小、类型）必须持久化在 c.state 中（如果无界，则在 c.kv 中），即使物理引擎句柄（不可序列化）位于 c.vars 中。重启时，run() 应从持久化数据中重新创建运行时对象。

除非另有说明，否则假设用户正在部署到 Rivet Cloud。如果用户是自托管，请阅读下面的自托管指南。

验证 Rivet Actors 在本地开发环境中正常工作
提示用户选择要部署到的提供商（请参阅 Connect 了解提供商列表，例如 Vercel、Railway 等）
遵循该给定提供商的部署指南。当需要手动干预时，您需要指导用户。

RivetKit OpenAPI 规范可在技能目录的 openapi.json 文件中找到。该文件记录了用于管理 actors 的所有 HTTP 端点。

Rivet 域名是 rivet.dev，而不是 rivet.gg

TypeScript 注意事项：Actor 客户端推断

在多文件 TypeScript 项目中，当两个 actors 都使用 c.client<typeof registry>() 时，双向 actor 调用可能会创建循环类型依赖。
症状通常包括 c.state 变为 unknown，actor 方法可能变为 undefined，或者在第一次跨 actor 调用后出现 TS2322 / TS2722 错误。
如果一个操作返回另一个 actor 调用的结果，请优先在该操作上使用显式返回类型注解，而不是依赖通过 c.client<typeof registry>() 的推断。
如果显式返回类型不够，请仅对该操作需要的 actors 使用更窄的客户端或注册表类型。
作为最后的手段，为注册表类型传递 unknown，并明确说明这将在该调用点放弃类型安全性。

长生命周期、有状态计算：每个计算单元都像一个小型服务器，在请求之间记住事物——无需从数据库重新获取数据或担心超时。类似于 AWS Lambda，但具有内存且无超时。
极速读写：状态存储在您的计算所在的同一台机器上，因此读写速度极快。无需数据库往返，无延迟峰值。状态会持久化到 Rivet 进行长期存储，因此可以在服务器重启后存活。
实时性：通过 WebSocket 实时更新状态和广播更改。无需外部发布/订阅系统，无需轮询——只需内置的低延迟事件。
无限扩展：自动从零扩展到数百万个并发 actors。仅按使用量付费，即时扩展，无冷启动。
容错性：内置错误处理和恢复。Actors 在失败时自动重启，同时保持状态完整性并继续操作。

何时使用 Rivet Actors

AI 智能体与沙盒：多步骤工具链、对话记忆、沙盒编排。
多人或协作应用：CRDT 文档、共享光标、实时仪表板、聊天。
工作流自动化：后台作业、cron、速率限制器、持久队列、背压控制。
数据密集型后端：地理分布式或按租户的数据库、内存缓存、分片 SQL。
网络工作负载：WebSocket 服务器、自定义协议、本地优先同步、边缘扇出。

import { actor, event, setup } from "rivetkit";

const counter = actor({
  state: { count: 0 },
  events: {
    count: event<number>(),
  },
  actions: {
    increment: (c, amount: number) => {
      c.state.count += amount;
      c.broadcast("count", c.state.count);
      return c.state.count;
    },
  },
});

export const registry = setup({
  use: { counter },
});

如果适用，与用户现有的服务器集成。否则，默认为 Hono。

import { registry } from "./actors";

export default registry.serve();

import { Hono } from "hono";
import { registry } from "./actors";

const app = new Hono();
app.all("/api/rivet/*", (c) => registry.handler(c.req.raw));

export default app;

import { Elysia } from "elysia";
import { registry } from "./actors";

const app = new Elysia()
	.all("/api/rivet/*", (c) => registry.handler(c.request));

export default app;

使用与您的应用匹配的客户端 SDK：

在重启、崩溃和部署后仍然存在的持久化数据。状态会持久化到 Rivet Cloud 或 Rivet 自托管环境，因此如果当前进程崩溃或退出，状态可以在重启后存活。

import { actor } from "rivetkit";

const counter = actor({
  state: { count: 0 },
  actions: {
    increment: (c) => c.state.count += 1,
  },
});

import { actor } from "rivetkit";

interface CounterState {
  count: number;
}

const counter = actor({
  state: { count: 0 } as CounterState,
  createState: (c, input: { start?: number }): CounterState => ({
    count: input.start ?? 0,
  }),
  actions: {
    increment: (c) => c.state.count += 1,
  },
});

键唯一标识 actor 实例。使用复合键（数组）进行分层寻址：

import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const chatRoom = actor({
  state: { messages: [] as string[] },
  actions: {
    getRoomInfo: (c) => ({ org: c.key[0], room: c.key[1] }),
  },
});

const registry = setup({ use: { chatRoom } });
const client = createClient<typeof registry>();

// 复合键: [org, room]
client.chatRoom.getOrCreate(["org-acme", "general"]);

// 通过 c.key 在 actor 内部访问键

当 userId 包含用户数据时，不要使用字符串插值如 "org:${userId}" 来构建键。请改用数组以防止键注入攻击。

在创建 actors 时传递初始化数据。

import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const game = actor({
  createState: (c, input: { mode: string }) => ({ mode: input.mode }),
  actions: {},
});

const registry = setup({ use: { game } });
const client = createClient<typeof registry>();

// 客户端用法
const gameHandle = client.game.getOrCreate(["game-1"], {
  createWithInput: { mode: "ranked" }
});

在重启后不会保留的临时数据。用于不可序列化的对象（事件发射器、连接等）。

import { actor } from "rivetkit";

const counter = actor({
  state: { count: 0 },
  vars: { lastAccess: 0 },
  actions: {
    increment: (c) => {
      c.vars.lastAccess = Date.now();
      return c.state.count += 1;
    },
  },
});

import { actor } from "rivetkit";

const counter = actor({
  state: { count: 0 },
  createVars: () => ({
    emitter: new EventTarget(),
  }),
  actions: {
    increment: (c) => {
      c.vars.emitter.dispatchEvent(new Event("change"));
      return c.state.count += 1;
    },
  },
});

操作是客户端和其他 actors 与 actor 通信的主要方式。

import { actor } from "rivetkit";

const counter = actor({
  state: { count: 0 },
  actions: {
    increment: (c, amount: number) => (c.state.count += amount),
    getCount: (c) => c.state.count,
  },
});

事件支持从 actors 到已连接客户端的实时通信。

import { actor, event } from "rivetkit";

const chatRoom = actor({
  state: { messages: [] as string[] },
  events: {
    newMessage: event<{ text: string }>(),
  },
  actions: {
    sendMessage: (c, text: string) => {
      // 广播给所有已连接的客户端
      c.broadcast("newMessage", { text });
    },
  },
});

通过 c.conn 访问当前连接，或通过 c.conns 访问所有已连接的客户端。使用 c.conn.id 或 c.conn.state 来安全地识别谁正在调用一个操作。连接状态通过 connState 或 createConnState 初始化，后者接收客户端在连接时传递的参数。

静态连接初始状态

import { actor } from "rivetkit";

const chatRoom = actor({
  state: {},
  connState: { visitorId: 0 },
  onConnect: (c, conn) => {
    conn.state.visitorId = Math.random();
  },
  actions: {
    whoAmI: (c) => c.conn.state.visitorId,
  },
});

动态连接初始状态

import { actor } from "rivetkit";

const chatRoom = actor({
  state: {},
  // 从客户端传递的参数
  createConnState: (c, params: { userId: string }) => ({
    userId: params.userId,
  }),
  actions: {
    // 访问当前连接的状态和参数
    whoAmI: (c) => ({
      state: c.conn.state,
      params: c.conn.params,
    }),
    // 使用 c.conns 遍历所有连接
    notifyOthers: (c, text: string) => {
      for (const conn of c.conns.values()) {
        if (conn !== c.conn) conn.send("notification", { text });
      }
    },
  },
});

使用队列在 run 循环中按顺序处理持久化消息。

import { actor, queue } from "rivetkit";

const counter = actor({
  state: { value: 0 },
  queues: {
    increment: queue<{ amount: number }>(),
  },
  run: async (c) => {
    for await (const message of c.queue.iter()) {
      c.state.value += message.body.amount;
    }
  },
});

当您的 run 逻辑需要持久化、可重放的多步骤执行时，请使用工作流。

import { actor, queue } from "rivetkit";
import { workflow } from "rivetkit/workflow";

const worker = actor({
  state: { processed: 0 },
  queues: {
    tasks: queue<{ url: string }>(),
  },
  run: workflow(async (ctx) => {
    await ctx.loop("task-loop", async (loopCtx) => {
        const message = await loopCtx.queue.next("wait-task");

        await loopCtx.step("process-task", async () => {
          await processTask(message.body.url);
          loopCtx.state.processed += 1;
        });

      });
  }),
});

async function processTask(url: string): Promise<void> {
  const res = await fetch(url, { method: "POST" });
  if (!res.ok) throw new Error(`Task failed: ${res.status}`);
}

Actors 可以使用 c.client() 调用其他 actors。

import { actor, setup } from "rivetkit";

const inventory = actor({
  state: { stock: 100 },
  actions: {
    reserve: (c, amount: number) => { c.state.stock -= amount; }
  }
});

const order = actor({
  state: {},
  actions: {
    process: async (c) => {
      const client = c.client<typeof registry>();
      await client.inventory.getOrCreate(["main"]).reserve(1);
    },
  },
});

const registry = setup({ use: { inventory, order } });

安排操作在延迟后或在特定时间运行。调度在重启、升级和崩溃后仍然存在。

import { actor, event } from "rivetkit";

const reminder = actor({
  state: { message: "" },
  events: {
    reminder: event<{ message: string }>(),
  },
  actions: {
    // 安排操作在延迟（毫秒）后运行
    setReminder: (c, message: string, delayMs: number) => {
      c.state.message = message;
      c.schedule.after(delayMs, "sendReminder");
    },
    // 安排操作在特定时间戳运行
    setReminderAt: (c, message: string, timestamp: number) => {
      c.state.message = message;
      c.schedule.at(timestamp, "sendReminder");
    },
    sendReminder: (c) => {
      c.broadcast("reminder", { message: c.state.message });
    },
  },
});

使用 c.destroy() 永久删除一个 actor 及其状态。

import { actor } from "rivetkit";

const userAccount = actor({
  state: { email: "", name: "" },
  onDestroy: (c) => {
    console.log(`Account ${c.state.email} deleted`);
  },
  actions: {
    deleteAccount: (c) => {
      c.destroy();
    },
  },
});

Actors 支持用于初始化、后台处理、连接、网络和状态更改的钩子。使用 run 进行长生命周期的后台循环，并在关闭时使用 c.aborted 或 c.abortSignal 干净地退出。

import { actor, event, queue } from "rivetkit";

interface RoomState {
  users: Record<string, boolean>;
  name?: string;
}

interface RoomInput {
  roomName: string;
}

interface ConnState {
  userId: string;
  joinedAt: number;
}

const chatRoom = actor({
  state: { users: {} } as RoomState,
  vars: { startTime: 0 },
  connState: { userId: "", joinedAt: 0 } as ConnState,
  events: {
    stateChanged: event<RoomState>(),
  },
  queues: {
    work: queue<{ task: string }>(),
  },

  // 状态和变量初始化
  createState: (c, input: RoomInput): RoomState => ({ users: {}, name: input.roomName }),
  createVars: () => ({ startTime: Date.now() }),

  // Actor 生命周期
  onCreate: (c) => console.log("created", c.key),
  onDestroy: (c) => console.log("destroyed"),
  onWake: (c) => console.log("actor started"),
  onSleep: (c) => console.log("actor sleeping"),
  run: async (c) => {
    for await (const message of c.queue.iter()) {
      console.log("processing", message.body.task);
    }
  },
  onStateChange: (c, newState) => c.broadcast("stateChanged", newState),

  // 连接生命周期
  createConnState: (c, params): ConnState => ({ userId: (params as { userId: string }).userId, joinedAt: Date.now() }),
  onBeforeConnect: (c, params) => { /* validate auth */ },
  onConnect: (c, conn) => console.log("connected:", conn.state.userId),
  onDisconnect: (c, conn) => console.log("disconnected:", conn.state.userId),

  // 网络
  onRequest: (c, req) => new Response(JSON.stringify(c.state)),
  onWebSocket: (c, socket) => socket.addEventListener("message", console.log),

  // 响应转换
  onBeforeActionResponse: <Out>(c: unknown, name: string, args: unknown[], output: Out): Out => output,

  actions: {},
});

在 actor 定义之外编写辅助函数时，使用 *ContextOf<typeof myActor> 来提取正确的上下文类型。不要手动定义自己的上下文接口——始终从 actor 定义派生它。

import { actor, ActionContextOf } from "rivetkit";

const gameRoom = actor({
  state: { players: [] as string[], score: 0 },
  actions: {
    addPlayer: (c, playerId: string) => {
      validatePlayer(c, playerId);
      c.state.players.push(playerId);
    },
  },
});

// 正确：从 actor 定义派生上下文类型
function validatePlayer(c: ActionContextOf<typeof gameRoom>, playerId: string) {
  if (c.state.players.includes(playerId)) {
    throw new Error("Player already in room");
  }
}

// 错误：不要像这样手动定义上下文类型
// type MyContext = { state: { players: string[] }; ... };

使用 UserError 抛出安全返回给客户端的错误。传递 metadata 以包含结构化数据。其他错误会转换为通用的"内部错误"以确保安全。

import { actor, UserError } from "rivetkit";

const user = actor({
  state: { username: "" },
  actions: {
    updateUsername: (c, username: string) => {
      if (username.length < 3) {
        throw new UserError("Username too short", {
          code: "username_too_short",
          metadata: { minLength: 3, actual: username.length },
        });
      }
      c.state.username = username;
    },
  },
});

import { actor, setup } from "rivetkit";
import { createClient, ActorError } from "rivetkit/client";

const user = actor({
  state: { username: "" },
  actions: { updateUsername: (c, username: string) => { c.state.username = username; } }
});

const registry = setup({ use: { user } });
const client = createClient<typeof registry>();

try {
  await client.user.getOrCreate([]).updateUsername("ab");
} catch (error) {
  if (error instanceof ActorError) {
    console.log(error.code);     // "username_too_short"
    console.log(error.metadata); // { minLength: 3, actual: 2 }
  }
}

低级 HTTP 和 WebSocket 处理器

对于自定义协议或需要直接访问 HTTP Request/Response 或 WebSocket 连接的库集成，请使用 onRequest 和 onWebSocket。

通过显示名称和图标自定义 actors 在 UI 中的显示方式。建议始终为 actors 提供名称和图标，以便在仪表板中更容易区分它们。

import { actor } from "rivetkit";

const chatRoom = actor({
  options: {
    name: "Chat Room",
    icon: "💬",  // 或 FontAwesome: "comments", "chart-line", 等。
  },
  // ...
});

完整的客户端指南请参见：

Actors 通过隔离状态和消息传递自然地扩展。使用以下模式构建您的应用程序：

每个实体一个 Actor

为每个用户、文档或房间创建一个 actor。使用复合键来限定实体的作用域：

import { createClient } from "rivetkit/client";
import type { registry } from "./actors";

const client = createClient<typeof registry>();

// 单个键：每个用户一个 actor
client.user.getOrCreate(["user-123"]);

// 复合键：限定在组织内的文档
client.document.getOrCreate(["org-acme", "doc-456"]);



import { actor, setup } from "rivetkit";

export const user = actor({
  state: { name: "" },
  actions: {},
});

export const document = actor({
  state: { content: "" },
  actions: {},
});

export const registry = setup({ use: { user, document } });

协调器与数据 Actors

数据 actors 处理核心逻辑（聊天室、游戏会话、用户数据）。协调器 actors 跟踪和管理数据 actors 的集合——将它们视为索引。

import { actor, setup } from "rivetkit";

// 协调器：跟踪组织内的聊天室
export const chatRoomList = actor({
  state: { rooms: [] as string[] },
  actions: {
    addRoom: async (c, name: string) => {
      // 创建聊天室 actor
      const client = c.client<typeof registry>();
      await client.chatRoom.create([c.key[0], name]);
      c.state.rooms.push(name);
    },
    listRooms: (c) => c.state.rooms,
  },
});

// 数据 actor：处理单个聊天室
export const chatRoom = actor({
  state: { messages: [] as string[] },
  actions: {
    send: (c, msg: string) => { c.state.messages.push(msg); },
  },
});

export const registry = setup({ use: { chatRoomList, chatRoom } });



import { createClient } from "rivetkit/client";
import type { registry } from "./actors";

const client = createClient<typeof registry>();

// 每个组织的协调器
const coordinator = client.chatRoomList.getOrCreate(["org-acme"]);
await coordinator.addRoom("general");
await coordinator.addRoom("random");

// 访问由协调器创建的聊天室
client.chatRoom.get(["org-acme", "general"]);

在 actor 内部使用 run 循环进行连续的后台工作。按顺序处理队列消息、按间隔运行逻辑、流式传输 AI 响应或协调长时间运行的任务。

import { actor, queue, setup } from "rivetkit";

const counterWorker = actor({
  state: { value: 0 },
  queues: {
    mutate: queue<{ delta: number }>(),
  },
  run: async (c) => {
    for await (const message of c.queue.iter()) {
      c.state.value += message.body.delta;
    }
  },
  actions: {
    getValue: (c) => c.state.value,
  },
});

const registry = setup({ use: { counterWorker } });

使用此模式处理长生命周期、持久化的工作流，这些工作流初始化资源、在循环中处理命令，然后进行清理。

import { actor, queue, setup } from "rivetkit";
import { Loop, workflow } from "rivetkit/workflow";

type WorkMessage = { amount: number };
type ControlMessage = { type: "stop"; reason: string };

const worker = actor({
  state: {
    phase: "idle" as "idle" | "running" | "stopped",
    processed: 0,
    total: 0,
    stopReason: null as string | null,
  },
  queues: {
    work: queue<WorkMessage>(),
    control: queue<ControlMessage>(),
  },
  run: workflow(async (ctx) => {
    await ctx.step("setup", async () => {
      await fetch("https://api.example.com/workers/init", { method: "POST" });
      ctx.state.phase = "running";
      ctx.state.stopReason = null;
    });

    const stopReason = await ctx.loop("worker-loop", async (loopCtx) => {
        const message = await loopCtx.queue.next("wait-command", {
          names: ["work", "control"],
        });

        if (message.name === "work") {
          await loopCtx.step("apply-work", async () => {
            await fetch("https://api.example.com/workers/process", {
              method: "POST",
              body: JSON.stringify({ amount: message.body.amount }),
            });
            loopCtx.state.processed += 1;
            loopCtx.state.total += message.body.amount;
          });
          return;
        }

        return Loop.break((message.body as ControlMessage).reason);
      });

    await ctx.step("teardown", async () => {
      await fetch("https://api.example.com/workers/shutdown", { method: "POST" });
      ctx.state.phase = "stopped";
      ctx.state.stopReason = stopReason;
    });
  }),
});

const registry = setup({ use: { worker } });

操作不是持久化的。将它们用于实时读取、临时数据和低延迟通信，如玩家输入。
队列是持久化的。使用它们通过运行循环序列化变更，避免与 SQLite 和其他本地状态的竞态条件。调用者仍然可以等待队列工作的响应。

身份验证、安全性与 CORS

在 onBeforeConnect 或 createConnState 中验证凭据，并抛出错误以拒绝未经授权的连接。
在操作中使用 c.conn.state 来安全地识别用户，而不是信任操作参数。
对于跨域访问，请在 onBeforeConnect 中验证请求来源。

部署新代码时，设置一个版本号，以便 Rivet 可以将新的 actors 路由到最新的运行器，并可选择性地排空旧的运行器。使用构建时间戳、git 提交计数或 CI 构建编号作为版本。在部署到生产环境之前，配置版本控制非常重要。没有版本控制，actors 可能会因为运行在较旧的运行器版本上而退化，并且现有的 actors 永远不会被迫迁移到新的运行器。它们将无限期地在旧的运行器上运行，直到退出。

切勿构建"上帝" actor

不要将所有逻辑放在一个 actor 中。一个上帝 actor 通过一个瓶颈序列化每个操作，扼杀并行性，并使整个系统作为一个单元失败。按实体拆分为专注的 actors。

切勿为每个请求创建一个 actor

Actors 是长生命周期的，并在请求之间维护状态。为每个传入请求创建一个新的 actor 会丢弃该模型的核心优势，并浪费资源在 actor 的创建和销毁上。将 actors 用于持久化实体，将常规函数用于无状态工作。

🇺🇸English

Rivet Actors

Build high-performance, long-lived, in-memory processes on Rivet's actor runtime. Use this skill whenever HTTP endpoints, databases, or queues no longer meet the requirements for AI agents, realtime collaboration, workflow orchestration, or geo-distributed data.

What To Do If You Get Stuck

If something is not working as intended or you are stuck, prompt the user to join the Rivet Discord or file an issue on the Rivet GitHub to report an issue and get help.

Provide the user with a pre-generated report with:

Symptoms
- If this is happening in local dev, deployed, or both
- The error you're seeing
- Relevant source code related to this
What you've tried to solve it
Environment
- RivetKit version
- Runtime (Node, Bun, etc) including version
- If applicable, provider in use (e.g. Vercel, Railway, etc)
- If applicable, HTTP router in use (e.g. Hono, Express, Elysia)

Debugging Actors

Use the inspector HTTP API to examine running actors. These endpoints are accessible through the gateway at /gateway/{actor_id}/inspector/*. Key endpoints:

GET /inspector/summary - full actor snapshot (state, connections, RPCs, queue)
GET /inspector/state / PATCH /inspector/state - read/write actor state
GET /inspector/connections - active connections
GET /inspector/rpcs - available actions
POST /inspector/action/{name} - execute an action with {"args": [...]}
GET /inspector/queue?limit=50 - queue status
GET /inspector/traces?startMs=0&endMs=...&limit=1000 - trace spans (OTLP JSON)
GET /inspector/workflow-history - workflow history and status

In local dev, no auth token is needed. In production, pass Authorization: Bearer <RIVET_INSPECTOR_TOKEN>. See the debugging docs for details.

Citing Sources

When providing information from Rivet documentation, cite the canonical URL so users can learn more. Each reference file includes its canonical URL in the header metadata.

How to cite:

Use inline links for key concepts: "Use actor keys to uniquely identify instances."
Add a "Learn more" link after explanations for complex topics

Finding canonical URLs:

The Reference Map below links to reference files. Each file's header contains:

> Canonical URL: https://rivet.dev/docs/actors/actions

Use that canonical URL when citing, not the reference file path.

Examples:

Actions → https://rivet.dev/docs/actors/actions
React client → https://rivet.dev/docs/clients/react
Self-hosting on Kubernetes → https://rivet.dev/docs/self-hosting/kubernetes

First Steps

Install RivetKit (latest: 2.1.6)
```
npm install rivetkit@2.1.6
```
Define a registry with setup({ use: { /* actors */ } }).
Expose registry.serve() or registry.handler() (serverless) or registry.startRunner() (runner mode). Prefer serverless mode unless the user has a specific reason to use runner mode.
Verify /api/rivet/metadata returns 200 before deploying.
Configure Rivet Cloud or self-hosted engine
- You must configure versioning for production builds. This is not needed for local development. See Versions & Upgrades.
Integrate clients (see client guides below for JavaScript, React, or Swift)
Prompt the user if they want to deploy. If so, go to Deploying Rivet Backends.

For more information, read the quickstart guide relevant to the user's project.

Error Handling Policy

Prefer fail-fast behavior by default.
Avoid try/catch unless it is required for a real recovery path, cleanup boundary, or to add actionable context.
Never swallow errors. If you add a catch, you must handle the error explicitly, at minimum by logging it.
When you cannot recover, log context and rethrow.

State vs Vars: Persistence Rules

c.vars is ephemeral. Data in c.vars is lost on every restart, crash, upgrade, or sleep/wake cycle. Only use c.vars for non-serializable objects (e.g., physics engines, WebSocket references, event emitters, caches) or truly transient runtime data (e.g., current input direction that doesn't matter after disconnect).

Persistent storage options. Any data that must survive restarts belongs in one of these, NOT in c.vars:

c.state — CBOR-serializable data for small, bounded datasets. Ideal for configuration, counters, small player lists, phase flags, etc. Keep under 128 KB. Do not store unbounded or growing data here (e.g., chat logs, event histories, spawned entity lists that grow without limit). State is read/written as a single blob on every persistence cycle.
c.kv — Key-value store for unbounded data. This is what c.state uses under the hood. Supports binary values. Use for larger or variable-size data like user inventories, world chunks, file blobs, or any collection that may grow over time. Keys are scoped to the actor instance.
c.db — SQLite database for structured or complex data. Use when you need queries, indexes, joins, aggregations, or relational modeling. Ideal for leaderboards, match histories, player pools, or any data that benefits from SQL.

Common mistake: Storing meaningful game/application data in c.vars instead of persisting it. For example, if users can spawn objects in a physics simulation, the spawn definitions (position, size, type) must be persisted in c.state (or c.kv if unbounded), even though the physics engine handles (non-serializable) live in c.vars. On restart, run() should recreate the runtime objects from the persisted data.

Deploying Rivet Backends

Assume the user is deploying to Rivet Cloud, unless otherwise specified. If user is self-hosting, read the self-hosting guides below.

Verify that Rivet Actors are working in local dev
Prompt the user to choose a provider to deploy to (see Connect for a list of providers, such as Vercel, Railway, etc)
Follow the deploy guide for that given provider. You will need to instruct the user when you need manual intervention.

API Reference

The RivetKit OpenAPI specification is available in the skill directory at openapi.json. This file documents all HTTP endpoints for managing actors.

Misc Notes

The Rivet domain is rivet.dev, not rivet.gg

TypeScript Caveat: Actor Client Inference

In multi-file TypeScript projects, bidirectional actor calls can create a circular type dependency when both actors use c.client<typeof registry>().
Symptoms usually include c.state becoming unknown, actor methods becoming possibly undefined, or TS2322 / TS2722 errors after the first cross-actor call.
If an action returns the result of another actor call, prefer an explicit return type annotation on that action instead of relying on inference through c.client<typeof registry>().
If explicit return types are not enough, use a narrower client or registry type for only the actors that action needs.
As a last resort, pass unknown for the registry type and be explicit that this gives up type safety at that call site.

Features

Long-Lived, Stateful Compute : Each unit of compute is like a tiny server that remembers things between requests – no need to re-fetch data from a database or worry about timeouts. Like AWS Lambda, but with memory and no timeouts.
Blazing-Fast Reads & Writes: State is stored on the same machine as your compute, so reads and writes are ultra-fast. No database round trips, no latency spikes. State is persisted to Rivet for long term storage, so it survives server restarts.
Realtime : Update state and broadcast changes in realtime with WebSockets. No external pub/sub systems, no polling – just built-in low-latency events.
Infinitely Scalable : Automatically scale from zero to millions of concurrent actors. Pay only for what you use with instant scaling and no cold starts.
Fault Tolerant : Built-in error handling and recovery. Actors automatically restart on failure while preserving state integrity and continuing operations.

When to Use Rivet Actors

AI agents & sandboxes: multi-step toolchains, conversation memory, sandbox orchestration.
Multiplayer or collaborative apps : CRDT docs, shared cursors, realtime dashboards, chat.
Workflow automation : background jobs, cron, rate limiters, durable queues, backpressure control.
Data-intensive backends : geo-distributed or per-tenant databases, in-memory caches, sharded SQL.
Networking workloads : WebSocket servers, custom protocols, local-first sync, edge fanout.

Minimal Project

Backend

actors.ts

import { actor, event, setup } from "rivetkit";

const counter = actor({
  state: { count: 0 },
  events: {
    count: event<number>(),
  },
  actions: {
    increment: (c, amount: number) => {
      c.state.count += amount;
      c.broadcast("count", c.state.count);
      return c.state.count;
    },
  },
});

export const registry = setup({
  use: { counter },
});

server.ts

Integrate with the user's existing server if applicable. Otherwise, default to Hono.

No Framework

import { registry } from "./actors";

export default registry.serve();

Hono

import { Hono } from "hono";
import { registry } from "./actors";

const app = new Hono();
app.all("/api/rivet/*", (c) => registry.handler(c.req.raw));

export default app;

Elysia

import { Elysia } from "elysia";
import { registry } from "./actors";

const app = new Elysia()
	.all("/api/rivet/*", (c) => registry.handler(c.request));

export default app;

Client Docs

Use the client SDK that matches your app:

Actor Quick Reference

In-Memory State

Persistent data that survives restarts, crashes, and deployments. State is persisted on Rivet Cloud or Rivet self-hosted, so it survives restarts if the current process crashes or exits.

Static Initial State

import { actor } from "rivetkit";

const counter = actor({
  state: { count: 0 },
  actions: {
    increment: (c) => c.state.count += 1,
  },
});

Dynamic Initial State

import { actor } from "rivetkit";

interface CounterState {
  count: number;
}

const counter = actor({
  state: { count: 0 } as CounterState,
  createState: (c, input: { start?: number }): CounterState => ({
    count: input.start ?? 0,
  }),
  actions: {
    increment: (c) => c.state.count += 1,
  },
});

RivetKit Actor 运行时 - 构建高性能长生命周期内存进程，适用于AI智能体与实时协作

🇨🇳中文介绍

Rivet Actors

遇到困难时该怎么办

调试 Actors

相关 Skills

引用来源

第一步

错误处理策略

状态与变量：持久化规则

部署 Rivet 后端

API 参考

杂项说明

TypeScript 注意事项：Actor 客户端推断

特性

何时使用 Rivet Actors

最小化项目

后端

无框架

Hono

Elysia

客户端文档

Actor 快速参考

内存状态

静态初始状态

动态初始状态

键

输入

临时变量

静态初始变量

动态初始变量

操作

事件与广播

连接

静态连接初始状态

动态连接初始状态

队列

工作流

Actor 间通信

调度

销毁 Actors

生命周期钩子

上下文类型

错误

Actor

客户端

低级 HTTP 和 WebSocket 处理器

图标与名称

客户端文档

常见模式

每个实体一个 Actor

协调器与数据 Actors

运行循环

工作流循环

操作与队列

身份验证、安全性与 CORS

版本与升级

反模式

切勿构建"上帝" actor

切勿为每个请求创建一个 actor

参考地图

Actors

🇺🇸English

Rivet Actors

What To Do If You Get Stuck

Debugging Actors

Citing Sources

First Steps

Error Handling Policy

State vs Vars: Persistence Rules

Deploying Rivet Backends

API Reference

Misc Notes

TypeScript Caveat: Actor Client Inference

Features

When to Use Rivet Actors

Minimal Project

Backend

No Framework

Hono