Actors

The primitive for agent orchestration, realtime, and per-tenant databases.

One Actor per agent, per session, per user. An Actor is a long-lived process with durable state, a queue, realtime connections, and scheduling, addressed by key and scheduled by the control plane. The same primitive powers realtime apps, multiplayer, and collaborative state, and every other product on this site is built on it.

A first actor

Define an actor with state and actions, register it, and call it from a typed client.

import { actor, setup } from "rivetkit";

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

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

registry.start();

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

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

// Get or create a counter actor for the key "my-counter"
const counter = client.counter.getOrCreate(["my-counter"]);

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

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

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

One primitive, every stateful workload

• Agent orchestration. One Actor per agent preserves identity, state, and session across long-running work. Add agentOS when the agent also needs files, processes, a shell, and networking.
• Realtime and multiplayer. WebSockets and event broadcast built in. One Actor per room, match, or channel keeps every client in sync without a separate realtime service.
• Per-tenant databases. One Actor per tenant, keyed by tenant ID, owns that tenant’s entire dataset. No shared tables and no tenant_id filters. See the per-tenant database guide.

What comes built in

• State: lives with the Actor for local reads and writes. Persist with SQLite or bring a database.
• Lifecycle: long-lived while active, sleeps when idle, wakes on the next request with state intact.
• Keys: each Actor is independently addressed and scheduled, so one design fans out with demand.
• Events: realtime bidirectional streaming over WebSockets.
• Queues: durable message queues for reliable async processing.
• Scheduling: timers and cron jobs inside the Actor.
• Actor-to-actor calls: address another Actor by key and call it as if it were local.
• Edge placement: configure placement with Rivet Cloud or your own control plane.

See inside every Actor

The Actor Inspector shows live state, connections, queues, workflow history, and SQLite data without building admin tooling. Rivet MCP lets your AI client find Actors, call actions, and open the same Inspector inline as it debugs your application.

The foundation the rest of Rivet builds on

• agentOS adds files, processes, a shell, and networking when an agent needs a computer. Every agentOS VM is an Actor.
• Workflows adds recorded steps, retries, and replay for work that outlives a process. Every workflow is an Actor.
• Dynamic Apps deploys the apps your agents build. Every app runs as Actors that scale to zero and wake on demand.

Develop locally, deploy your way

Run npm install rivetkit and start from a quickstart. Deploy the control plane yourself with the self-host guides, or use Rivet Cloud.