Getting Started

Rivet Actors

Rivet Actors allows you to deploy resilient, stateful services that maintain their state between requests using RivetKit. Use them for websocket servers, game backends, real-time collaboration services, and more.

This guide shows you how to get started quickly with RivetKit. For use cases that require low-level control, see the low-level actors API.

Step 1: Install RivetKit

Command Line

npm install @rivetkit/actor

Step 2: Create an Actor

Create a simple counter actor:

TypeScript

import { actor, setup } from "@rivetkit/actor";

export const counter = actor({
	state: { count: 0 },
	actions: {
		increment: (c, amount: number = 1) => {
			c.state.count += amount;
			c.broadcast("countChanged", c.state.count);
			return c.state.count;
		},
		getCount: (c) => c.state.count,
	},
});

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

Step 3: Setup Server

Choose your preferred web framework:

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

// Start RivetKit with memory driver (for development)
const { client, serve } = registry.createServer();

// Setup Hono app
const app = new Hono();

// Example API endpoint
app.post("/increment/:name", async (c) => {
	const name = c.req.param("name");

	// Get or create actor and call action
	const counter = client.counter.getOrCreate(name);
	const newCount = await counter.increment(1);

	return c.json({ count: newCount });
});

// Start server with RivetKit
serve(app);

Note

The /registry endpoint is automatically mounted by RivetKit and is required for client communication. When using serve() with Hono, this is handled automatically.

Step 4: Run Server

npx tsx --watch server.ts

Your server is now running at http://localhost:8080

Step 5: Test Your Actor

Test your counter actor using HTTP requests:

// Increment counter
const response = await fetch("http://localhost:8080/increment/my-counter", {
	method: "POST"
});

const result = await response.json();
console.log("Count:", result.count); // 1

Step 6: Deploy to Rivet

By default, RivetKit stores actor state on the local file system and will not scale in production.

Rivet provides open-source infrastructure to deploy & scale RivetKit. To deploy to Rivet, provide this config:

JSON

{
  "rivetkit": {
    "registry": "src/registry.ts",
    "server": "src/server.ts"
  }
}

And deploy with:

Command Line

npx rivet-cli@latest deploy

Your endpoint will be available at your Rivet project URL.

Connect Frontend to Rivet Actors

Create a type-safe client to connect from your frontend:

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

// Create typed client
const client = createClient<typeof registry>("http://localhost:8080");

// Use the counter actor directly
const counter = client.counter.getOrCreate(["my-counter"]);

// Call actions
const count = await counter.increment(3);
console.log("New count:", count);

// Get current state
const currentCount = await counter.getCount();
console.log("Current count:", currentCount);

// Listen to real-time events
const connection = counter.connect();
connection.on("countChanged", (newCount) => {
	console.log("Count changed:", newCount);
});

// Increment through connection
await connection.increment(1);

See the client documentation at rivetkit.org for more information.