README.md
</picture>
Rivet Actors are long-running, lightweight processes designed for stateful workloads. State lives in-memory with automatic persistence. Create one per agent, per session, or per user — with built-in workflows, queues, and scheduling.
Backend
const agent = actor({
// In-memory, persisted state for the actor
state: { messages: [] as Message[] },
// Long-running actor process
run: async (c) => {
// Process incoming messages from the queue
for await (const msg of c.queue.iter()) {
c.state.messages.push({ role: "user", content: msg.body.text });
const response = streamText({ model: openai("gpt-5"), messages: c.state.messages });
// Stream realtime events to all connected clients
for await (const delta of response.textStream) {
c.broadcast("token", delta);
}
c.state.messages.push({ role: "assistant", content: await response.text });
}
},
});
Client (frontend or backend)
// Connect to an actor
const agent = client.agent.getOrCreate("agent-123").connect();
// Listen for realtime events
agent.on("token", delta => process.stdout.write(delta));
// Send message to actor
await agent.queue.send("how many r's in strawberry?");
One Actor per agent, per session, per user — state, storage, and networking included.
Rivet provides:
Actors support:
One primitive that adapts to agents, workflows, collaboration, and more.
Rivet Actors vs. Traditional Infrastructure
| Metric | Rivet Actor | Kubernetes Pod | Virtual Machine |
|---|---|---|---|
| Cold start | ~20ms | ~6s | ~30s |
| Memory per instance | ~0.6KB | ~50MB | ~512MB |
| Idle cost | $0 | ~$85/mo (cluster) | ~$5/mo |
| Horizontal scale | Infinite | ~5k nodes | Manual |
| Multi-region | Global edge | 1 region | 1 region |
State
| Metric | Rivet Actor | Redis | Postgres |
|---|---|---|---|
| Read latency | 0ms | ~1ms | ~5ms |
Cold Start
Memory Per Instance
Read Latency
Idle Cost
Horizontal Scale
Multi-Region
Powerful debugging and monitoring tools from local development to production at scale.
<p align="center"> </p>RivetKit is a library. Connect it to Rivet Cloud or self-host when you need scaling, fault tolerance, and observability.
<table> <tr> <td width="33%" valign="top">Install a package and run locally. No servers, no infrastructure. Actors run in your process during development.
npm install rivetkit
Single Rust binary or Docker container. Works with Postgres, file system, or FoundationDB.
docker run -p 6420:6420 rivetdev/engine
Fully managed. Global edge network. Connects to your existing cloud — Vercel, Railway, AWS, wherever you already deploy.
</td> </tr> </table>Open source, permissively licensed — Self-hosting matters for enterprise deployments, cloud portability, and avoiding vendor lock-in. Apache 2.0 means you own your infrastructure. View on GitHub →
Give your coding agent the Rivet skills to create examples or integrate into existing projects:
npx skills add rivet-dev/skills
Works with Claude Code, Cursor, Windsurf, and other AI coding tools.
</td> <td width="50%" valign="top">Serverless, containers, or your own servers — Rivet Actors work with your existing infrastructure, frameworks, and tools.
Infrastructure: Vercel • Railway • AWS • Docker
Frameworks: React • Next.js • Hono • Express • Elysia • tRPC
Runtimes: Node.js • Bun • Deno • Cloudflare Workers
Tools: Vitest • Pino • AI SDK • OpenAPI • AsyncAPI
| Project | Description |
|---|---|
| RivetKit TypeScript | Client & server library for building actors |
| RivetKit Rust | Rust client (experimental) |
| RivetKit Python | Python client (experimental) |
| Rivet Engine | Rust orchestration engine |
| ↳ Pegboard | Actor orchestrator & networking |
| ↳ Gasoline | Durable execution engine |
| ↳ Guard | Traffic routing proxy |
| ↳ Epoxy | Multi-region KV store (EPaxos) |
| Dashboard | Inspector for debugging actors |
| Website | Source for rivet.dev |
| Documentation | Source for rivet.dev/docs |