Pool

A pool is a group of machines, called nodes, that run your Durable Objects. Each class runs on one pool. When a room wakes, the control plane starts it on one of its pool’s nodes.

Declare it

A pool is a Layer, given the control plane it joins:

src/cluster.ts

export const Default = RivetDocker.SwarmPool("Default").pipe(Layer.provide(Cluster));

The nodes connect out to the control plane and wait for rooms to run. Nothing connects in to them, so they need no public address and no load balancer.

Put a class on it

A class names its pool by providing it:

src/room.ts

export default class Room extends Rivet.DurableObject<Room>()(
  "Room",
  { main: import.meta.url },
  Effect.gen(function* () {
    // ...
  }).pipe(Effect.provide(Default)),
) {}

Each deploy builds one program for the pool, holding every class it runs, and rolls it out to the nodes.

Share a pool

Classes with similar needs share a pool and its machines. The rooms and the greeter run on the same nodes:

Defaultpool: Room, Greeter

node 1

lobbyRoom

samGreeter

node 2

kitchenRoom

Every node in a pool runs every class on it. The control plane starts each instance on one of them, so a node holds instances of both classes.

One pool is the right start. Fewer pools means fewer machines idling.

Split them

A class with different needs gets a pool of its own, so it can’t crowd out the rest. Rooms that transcode audio need bigger machines than rooms that only chat:

src/cluster.ts

export const Default = RivetAWS.EcsPool("Default").pipe(Layer.provide(Cluster));

export const Media = RivetAWS.EcsPool("Media", { cpu: 2048, memory: 4096 }).pipe(
  Layer.provide(Cluster),
);

Both join the same control plane, so a room on Default still calls a class on Media by name.

Scale it

More nodes run more rooms at once:

src/cluster.ts

export const Default = RivetDocker.SwarmPool("Default", { replicas: 3 }).pipe(Layer.provide(Cluster));

A single room still runs on one node at a time, so more nodes help a pool with many busy rooms, not one very busy room.

Run it on another cloud

A pool works with any control plane it can reach. Its nodes only connect out, so the control plane can be anywhere:

src/cluster.ts

export const Cluster = RivetHetzner.ServerControlPlane("Rivet");

export const Default = RivetRailway.ServicePool("Default").pipe(Layer.provide(Cluster));

Keep the two close when you can: every call to a room passes through the control plane.

Next, choose a platform: Docker, AWS, GCP, Kubernetes, Fly, Hetzner, Railway or Rivet Cloud.