rivet README

项目的 README,来自 github.com/rivet-dev/rivet。合并为一个 markdown 文件:README.md。

Rivet

Fast, high-density, scalable orchestration with Rivet Actors.
Built on S3 at SSD speeds.

4.99 ms p99 cold starts, 72 KB RAM per Actor, scales to billions

Quickstart • Documentation • Blog • Discord • X

What is Rivet?

Rivet Actors are long-lived processes with in-memory state, a SQLite database, WebSockets, and scheduling. You can create one for each agent, user, session, or tenant.

Use cases

Example

A minimal agent written from scratch. For a ready-made agent, use Pi Durable.

// server.ts
import { actor, setup } from "rivetkit";
import { db } from "rivetkit/db";
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";

// One Actor per agent, created on first use: agent.getOrCreate(["agent-123"])
export const agent = actor({
  // 1. SQLite: every agent has its own database, so history survives restarts
  db: db({
    onMigrate: async (db) => {
      await db.execute("CREATE TABLE IF NOT EXISTS messages (role TEXT, content TEXT)");
    },
  }),

  // 2. In-memory state: plain variables that live with the Actor, with no database round trip
  createVars: () => ({ online: new Map<string, string>() }),

  // 3. WebSockets: each client holds a live connection, and the Actor pushes to all of them
  onDisconnect: (c, conn) => {
    c.vars.online.delete(conn.id);
    c.broadcast("online", [...c.vars.online.values()]);
  },

  actions: {
    join: (c, user: string) => {
      c.vars.online.set(c.conn.id, user);
      c.broadcast("online", [...c.vars.online.values()]);
    },

    sendMessage: async (c, text: string) => {
      // Save the message
      await c.db.execute("INSERT INTO messages VALUES (?, ?)", "user", text);
      const messages = await c.db.execute("SELECT role, content FROM messages");

      // Stream tokens to every connected client
      const response = streamText({ model: openai("gpt-5"), messages });
      for await (const delta of response.textStream) {
        c.broadcast("token", delta);
      }

      // Save the response
      await c.db.execute("INSERT INTO messages VALUES (?, ?)", "assistant", await response.text);
    },
  },
});

export const registry = setup({ use: { agent } });
// client.ts (frontend or backend)
import { createClient } from "rivetkit/client";
import type { registry } from "./server";

const client = createClient<typeof registry>();

// Open a WebSocket connection to the agent
const agent = client.agent.getOrCreate(["agent-123"]).connect();

// Listen for realtime events
agent.on("online", users => console.log("online:", users));
agent.on("token", delta => process.stdout.write(delta));

// Call actions on the Actor
await agent.join("nathan");
await agent.sendMessage("how many r's in strawberry?");

Why run agents on Rivet Actors?

Each Actor gives the agent a long-lived process for long agent turns, in-memory state for context, a WebSocket server for multiplayer, durable SQLite storage for session transcripts and agent artifacts, and hibernation when idle.

Most of an agent's time is spent waiting on inference. When the agent loop runs inside a sandbox, you pay for a whole VM that sits mostly idle with low CPU usage.

Rivet Actors run the agent loop outside of the sandbox instead, often called "separating the head from the hands." The agent's state, memory, and context live in the Actor, and it reaches the sandbox through tools only when it needs to run code. This uses a fraction of the memory and limits the blast radius and trust boundary of the code it runs. Read more about running the harness outside of the sandbox.

Do I need a sandbox with a Rivet Actor?

Often not. An agent needs a sandbox only to run code it writes. Developers on Rivet use three patterns:

Getting Started

Use with your coding agent

Paste this prompt into Claude Code, Cursor, Codex, or any coding agent:

Run npx skills add rivet-dev/skills, then ask me what to build and run it locally.

Start from scratch

Rivet ships libraries built on top of Actors for common use cases.

How Actors compare to sandboxes

Metric Rivet Actor Sandbox
Cold start (p99) 4.99 ms 1.70 s
Memory per instance 72.4 KB 512 MiB
Storage SQLite on S3 Disk per sandbox
Storage cost 10.4× cheaper Replicated SSDs
Benchmark details & methodology

Features

Deployment Options

Option Description Get started
Local & self-host Run Rivet locally while you build. In production, run the control plane on Docker, Kubernetes, or a VM. S3 is the only dependency. Self-hosting docs
Rivet Cloud Fully managed, dedicated clusters on AWS or GCP in any region. Run your nodes on Rivet Cloud or bring your own. Dashboard
BYOC The control plane runs inside your own VPC on AWS, GCP, or Azure, fully managed by Rivet. Your data never leaves your cloud. BYOC docs

Every option runs the same control plane, from local dev to production. Talk to an engineer →

Works with the tools you already use

Typed SDKs for your backend and React hooks for your frontend. Rivet runs on native Node.js and Bun with no custom runtime, so your existing packages, tooling, and tests work unchanged.

Deploy nodes on: Docker Compose • Kubernetes • VM & bare metal • Hetzner • AWS ECS • Railway • Render

Frameworks: React • Effect

Runtimes: Node.js • Bun • Rust

Tools: Vitest • OpenTelemetry • Pino • AI SDK • OpenAPI • AsyncAPI

Request an integration →

FAQ

Does Rivet have BYOC?

Yes. Rivet deploys into your own cloud account, including air-gapped environments: the control plane and storage run inside your VPC while Rivet operates them. See the BYOC docs.

Does Rivet have a cloud?

Yes. Rivet Cloud runs fully managed, dedicated clusters on AWS or GCP in any region. It can run your app's Docker image as nodes on Rivet Cloud, or you can bring your own nodes.

Can I self-host Rivet?

Yes. Rivet is fully self-hostable; see the self-hosting docs. The control plane runs anywhere a container runs, with guides for Docker Compose, Kubernetes, VMs and bare metal, Hetzner, Railway, Render, and AWS ECS. For enterprise support with a self-hosted deployment, contact us.

Do I still need Postgres, FoundationDB, or NATS?

No. An object storage bucket is the only dependency: there is no database to run and no message bus, and control plane instances find each other through the bucket. Rivet works with Amazon S3, Google Cloud Storage, Azure Blob Storage, and any S3-compatible store such as MinIO, Cloudflare R2, or Hetzner Object Storage. A local filesystem backend is available for trying Rivet on one machine.

Is Rivet open-source?

Yes. Rivet is open source under the permissive Apache 2.0 license. You're looking at it.

Are Rivet Actors only for agents?

No. Rivet is a general actor platform at its core, with nothing specific to agents. For agents, you can use the optional agent library, which runs Pi Durable on Rivet Actors, or write your own agent from scratch.

How does Rivet compare to sandboxes?

A sandbox boots a VM or container per agent, which is slow to start and sits mostly idle. A Rivet Actor runs inside a shared node process: 72 KB and 4.99 ms p99 to start, versus 512 MiB and 1.70 s for a sandbox, and it hibernates when idle. To run untrusted code your agent writes, use agentOS.

How does Rivet compare to Cloudflare Durable Objects?

Rivet is often used as an open-source alternative to Cloudflare Durable Objects that is easy to self-host and scales. It also fixes many of the constraints of Durable Objects: no 128 MB memory cap, bottomless storage instead of a 10 GB SQLite limit, Actors are not randomly evicted, and you control the runtime because Actors run on vanilla Node.js or Bun instead of a custom runtime. Rivet also adds built-in connection handling, event broadcasting, durable scheduling and cron, full Vitest support, lifecycle hooks for draining, and control over Actor upgrades. See the Cloudflare Durable Objects comparison.

Does Rivet use a custom V8 runtime?

No. Rivet runs on native Node.js and Bun, so your existing packages, tooling, and tests work unchanged.

Is Rivet like Erlang, Akka, or Orleans?

Rivet implements the virtual actor pattern, which is closest to Orleans, but focuses on what modern workloads need: SQLite persistence instead of simple JSON stores and support for modern runtimes. Erlang and Akka do not provide virtual actors out of the box, though ecosystem packages exist that offer functionality comparable to Rivet Actors.

Does Rivet require microVMs, gVisor, or nested virtualization?

No. Rivet only needs a standard process that connects to the control plane over WebSocket. That process can be Node.js, Bun, Rust, or anything else.

Projects in This Repository

Project Description
RivetKit TypeScript Client & server library for building Actors
RivetKit Rust Rust SDK
RivetKit Python Python client (experimental)
RivetKit Swift Swift client (experimental)
Control Plane Rust control plane that schedules, routes, and persists Actors
↳ Pegboard Actor scheduling & networking
↳ Guard Traffic routing proxy
↳ Epoxy Multi-region KV store (EPaxos)
Documentation Source for rivet.dev/actors/docs
Examples Runnable examples

Community

License

Apache 2.0

rivet (rivet-dev/rivet)

正在搜索数据库…

6.9K ·GitHub
这是什么?Rivet 是一个用于有状态 Actors 的编排工具。Actors 是长期运行的进程,拥有持久化状态、内置的 SQLite 数据库、实时连接和调度功能,专为 AI 智能体、工作流、沙箱和协作应用而设计。它是开源的,可以自行托管,定位是比 Kubernetes Pod 或 Cloudflare Durable Objects 更轻量的替代方案。
这是我要引入的库,还是要运行的服务?它是一个可自行托管的控制平面,以单个 Rust 二进制文件的形式发布,并为后端提供类型化 SDK,为前端提供 React Hooks。你可以自己运行控制平面,也可以使用托管服务 Rivet Cloud。
我该如何让它运行起来?开发时,安装 Actors 并在本地运行控制平面,可使用 Node.js、Bun、React、Next.js、Rust 或 Effect 的启动模板;上线时,将同一个开源控制平面以容器形式运行在 Docker、Kubernetes 或虚拟机上。
运行它是否需要数据库或消息队列?不需要。唯一的依赖是一个对象存储桶(Amazon S3、Google Cloud Storage、Azure Blob Storage,或 MinIO、Cloudflare R2 等兼容 S3 的存储);无需运行任何数据库或消息总线。
自行托管实际需要什么?生产环境的自托管至少需要三个完全相同的控制平面实例(试用时一个就够),每个实例都要配一块持久化磁盘,每个集群还需要一个存储桶,以及运行你的 Actors 的节点。
这是为谁设计的?面向正在构建编程智能体的团队、为每位用户生成后端的智能体应用开发者、必须留在自有 VPC 内的企业内部智能体、个人长期运行的助手,以及协作文档或聊天室等实时应用。
我的数据必须离开我的基础设施吗?不需要。使用 BYOC 时,整个技术栈都运行在你自己的 VPC 和存储桶中;Rivet 仅通过出站连接进行管理,因此 Actor 数据不会离开你的账户。
Rivet 与 Cloudflare Durable Objects 相比如何?Rivet 没有 Durable Objects 的限制:没有 128 MB 的内存上限,存储容量不受 10 GB SQLite 上限的约束,Actors 不会被随机驱逐,并且 Actors 运行在标准的 Node.js 或 Bun 上,而不是定制的 V8 运行时。
我能构建哪些类型的 Actors?同一个控制平面可以调度通用 Actors、可在重启后保留记忆的持久化智能体、可重放的工作流、用于运行不受信任代码的沙箱环境(agentOS),以及为每位用户部署后端的预览版动态应用。
它能与我的编程智能体工具配合使用吗?可以。Rivet 为 Claude Code、Cursor、Windsurf 以及其他 AI 编程工具提供了技能,让它们能够搭建示例,或将 Actors 集成到现有项目中。
与 Kubernetes Pod 相比,Actors 的启动有多快、占用有多轻?基准测试显示:冷启动仅需 6.9 毫秒,而 Pod 约需 6 秒;每个 Actor 占用 72 KB 内存,而空闲 Pod 约占用 200 MB;在一个控制平面上可以运行数十亿个 Actors,而每个 Kubernetes 集群大约只能承载约 5000 个节点。
作者
rivet-dev
大小
419.2 MB
星标
6.9K
时长
3年
提交 · 90 天