Cloud

Actor Nodes

Deploy your app to a Rivet Cloud cluster as a Docker image.

Rivet Cloud runs your app’s Docker image as actor nodes on your cluster.

Requirements

A Rivet Cloud cluster
Docker

Steps

Write the server

import { createServer } from "node:http";
import { actor, setup } from "rivetkit";

const counter = actor({
	state: { count: 0 },
	actions: {
		increment: (c, amount: number) => (c.state.count += amount),
	},
});

const registry = setup({
	startEngine: false,
	startServices: false,
	runtime: "native",
	use: { counter },
});

// Connect to the cluster as an actor node.
registry.start();

// Your app's HTTP server. The cluster's public URL forwards to PORT.
createServer((_req, res) => {
	res.end("ok");
}).listen(Number(process.env.PORT ?? 8080));

// Metrics, collected with your logs. Keep this server on localhost.
createServer(async (_req, res) => {
	const metrics = await registry.routes.prometheusMetrics();
	res.writeHead(metrics.status, Object.fromEntries(metrics.headers));
	res.end(await metrics.text());
}).listen(Number(process.env.RIVETKIT_METRICS_PORT ?? 9464), "127.0.0.1");

Do not set RIVET_ENDPOINT, RIVET_TOKEN or RIVET_POOL. The cluster sets them on every deploy.

Add a Dockerfile

FROM node:24-bookworm-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev \
	&& rm -rf node_modules/@rivet-dev/agentos-* node_modules/@rivet-dev/agent-os-* node_modules/@agentos-software node_modules/@rivetkit/engine-cli-*
COPY . .
ENV NODE_ENV=production
CMD ["node", "server.ts"]

The rm -rf removes packages a node never uses, which keeps the image well under the 5 GiB limit.

Deploy

CLI

npx @rivetkit/cli login
npx @rivetkit/cli link --org my-org --cluster my-cluster
npx @rivetkit/cli deploy

Agent

Connect your agent to the Rivet MCP server at https://mcp.rivet.dev/mcp and ask it to deploy:

Deploy this app to my-cluster.

A deploy takes 5 to 10 minutes and prints a build ID.

Verify

curl https://my-cluster.onrivet.dev

Rolling back

Deploy an earlier build ID. Nothing is rebuilt.

npx @rivetkit/cli deploy --build <build-id>

See CLI for all deploy options.