File: cloud/docs/content/docs/index.mdx Copy Chapter

title: "Rivet Cloud" Copy Chapter

Rivet Cloud runs the control plane for you. You keep writing the same code and deploy it one of two ways:

• Bring your own compute. Run workers on your own infrastructure and point them at Rivet Cloud. Every platform in the Self-Host worker guides works this way.
• Rivet Compute. Hand Rivet a container and it runs your backend as well. See Rivet Compute.

Nothing here is required to use Rivet. If you would rather run the control plane yourself, see Self-Host.

Getting started Copy Chapter

1. Create a project at dashboard.rivet.dev.
2. Open Connect and pick how you want to deploy.
3. Copy the endpoint values, or the cloud token if you are deploying with Rivet Compute.

Tokens Copy Chapter

Rivet Cloud issues three kinds of token, and mixing them up is the most common source of 401s.

A pk_ token will fail against the Cloud API, and a cloud_api_ token will fail against the Engine API. They are not interchangeable.

In this section Copy Chapter

• Rivet Compute: deploy your backend as a container
• Preview Deployments: an isolated namespace per pull request

File: cloud/docs/content/docs/preview-deployments.mdx Copy Chapter

title: "Preview Deployments" Copy Chapter

A preview deployment gives each pull request its own Rivet namespace, so branch work never touches production state. The namespace is created when the PR opens and destroyed when it closes.

Which setup you use depends on where your workers run.

With Rivet Compute Copy Chapter

setup-ci writes a workflow that already does this:

npx @rivetkit/cli setup-ci
gh secret set RIVET_CLOUD_TOKEN

The generated .github/workflows/rivet-deploy.yml deploys production on push to your default branch, creates a namespace per pull request, posts the preview link as a comment, and cleans the namespace up on close. See Rivet Compute.

With Vercel Copy Chapter

Use the preview-namespace-action. It creates the namespace and writes RIVET_ENDPOINT and RIVET_PUBLIC_ENDPOINT into the Vercel preview environment, so the deployment picks them up with no manual configuration.

name: Rivet Preview

on:
  pull_request:
    types: [opened, synchronize, reopened]
  push:
    branches: [main]

concurrency:
  group: rivet-preview-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

jobs:
  rivet-preview:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: rivet-dev/preview-namespace-action@v1
        with:
          platform: vercel
          rivet-token: ${{ secrets.RIVET_CLOUD_TOKEN }}
          vercel-token: ${{ secrets.VERCEL_TOKEN }}

The action also configures the Vercel Deployment Protection bypass header, which is otherwise a common source of 401s from Rivet into preview deployments. See Vercel.

On other platforms Copy Chapter

Any platform works, as long as the pull-request build gets endpoint values for a fresh namespace instead of production's. Create the namespace with the Cloud API using a cloud_api_* token, inject the resulting endpoints as build-time environment variables, and delete the namespace when the pull request closes.

Next steps Copy Chapter

• Rivet Compute
• Tokens

File: packages/icons/README.md Copy Chapter

Rivet Icons

⚠️ Legal Notice Copy Chapter

This package is licensed exclusively for use in Rivet products and services. Using this package in any other product, project, or commercial application is strictly prohibited and may constitute a violation of Font Awesome's Terms of Service and intellectual property rights.

This package includes icons from Font Awesome Pro, which are licensed to Rivet for use in Rivet products only. If you wish to use Font Awesome Pro icons in your own projects, you must obtain your own license from Font Awesome.

Overview Copy Chapter

Rivet Icons is an icon library built on Font Awesome that provides pre-generated SVG icons for use in Rivet products. All icons (including Pro icons) are committed to the repository, making this package work out-of-the-box with no Font Awesome token required for end users.

Installation Copy Chapter

pnpm add @rivet-gg/icons

Usage Copy Chapter

import { Icon, faCheckCircle } from "@rivet-gg/icons";

Contributing Copy Chapter

Prerequisites Copy Section

For maintainers only: Obtain a Font Awesome Pro license and set the FONTAWESOME_PACKAGE_TOKEN environment variable to your Font Awesome Pro token. This is only required when vendoring new icons.

Adding new icons Copy Section

1. Ensure you have a FONTAWESOME_PACKAGE_TOKEN environment variable set
2. Modify scripts/generate-manifest.js to include new icons
3. Run pnpm manifest to generate a new manifest.json file
   • If you're getting an error about missing packages, run pnpm install in the src folder first
4. Run pnpm vendor to generate icon files:
   • src/index.gen.js
   • src/index.gen.ts
   • dist/index.js
5. Commit all changes including the generated files

Troubleshooting Copy Chapter

Icons not showing up Copy Section

All icons (including Font Awesome Pro icons) are pre-generated and committed to this repository. If icons aren't showing:

1. Make sure you have the peer dependencies installed:

   • @fortawesome/fontawesome-svg-core
   • @fortawesome/free-solid-svg-icons
   • @fortawesome/free-brands-svg-icons
   • @fortawesome/react-fontawesome
   • react and react-dom

2. Check that you're importing icons correctly:

   tsx Copy

   import { Icon, faCheckCircle } from "@rivet-gg/icons";

3. If the problem persists, contact us on Discord

For Maintainers: `Could not find package @fortawesome/pro-solid-svg-icons` Copy Section

This error occurs when running the vendor script without access to Font Awesome Pro packages. Make sure:

1. FONTAWESOME_PACKAGE_TOKEN environment variable is set
2. Run pnpm install in the src folder to install FA Pro packages
3. Run pnpm vendor again

File: src/content/self-host/control-plane/aws-ecs.mdx Copy Chapter

title: "AWS ECS" Copy Chapter

Requirements Copy Chapter

• An AWS account with ECS and Fargate available
• An EFS file system, or an RDS PostgreSQL instance, for persistence
• An Application Load Balancer in front of the service
• AWS Secrets Manager, or SSM Parameter Store, for the admin token

Steps Copy Chapter

aws secretsmanager create-secret \
  --name rivet/admin-token \
  --secret-string "$(openssl rand -hex 32)"

{
  "family": "rivet-engine",
  "requiresCompatibilities": ["FARGATE"],
  "networkMode": "awsvpc",
  "cpu": "1024",
  "memory": "2048",
  "containerDefinitions": [
    {
      "name": "rivet-engine",
      "image": "rivetdev/engine:2.3.3",
      "portMappings": [
        { "containerPort": 6420 },
        { "containerPort": 6421 }
      ],
      "environment": [
        { "name": "RIVET__FILE_SYSTEM__PATH", "value": "/data" }
      ],
      "secrets": [
        {
          "name": "RIVET__AUTH__ADMIN_TOKEN",
          "valueFrom": "arn:aws:secretsmanager:REGION:ACCOUNT:secret:rivet/admin-token"
        }
      ],
      "mountPoints": [
        { "sourceVolume": "rivet-data", "containerPath": "/data" }
      ]
    }
  ],
  "volumes": [
    {
      "name": "rivet-data",
      "efsVolumeConfiguration": { "fileSystemId": "fs-XXXXXXXX" }
    }
  ]
}

aws elbv2 modify-load-balancer-attributes \
  --load-balancer-arn <arn> \
  --attributes Key=idle_timeout.timeout_seconds,Value=3600

aws ecs describe-services --cluster <cluster> --services rivet-engine \
  --query 'services[0].deployments[0].rolloutState'

curl -X PUT "http://<load-balancer-host>/runner-configs/default?namespace=default" \
  -H "Authorization: Bearer $RIVET_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"datacenters":{"default":{"normal":{}}}}'

Scaling past one task Copy Chapter

EFS-backed file system storage is single-node: RocksDB cannot be shared between tasks. Before raising the desired count above one, move to RDS PostgreSQL and add NATS for pub/sub. See Storage.

Once on RDS, ECS Service Auto Scaling can drive the desired count. Use target tracking on average CPU at 60%, matching the Kubernetes manifests, and keep a minimum of two tasks so the service survives losing one. Leave the desired count at one for as long as the task is on EFS.

Next steps Copy Chapter

• Production checklist
• Deploy workers on AWS ECS
• Configuration reference

File: src/content/self-host/control-plane/backups.mdx Copy Chapter

title: "Backup & Restore" Copy Chapter

Everything the control plane persists lives in its storage backend, so backing up the control plane means backing up that backend. The engine itself is stateless between restarts and needs no separate backup.

What you must be able to restore:

• The storage backend. Actor state, namespaces, and runner configuration.
• Your configuration. The config file or environment variables, including the admin token. Losing the admin token locks you out of the dashboard and the API.

By backend Copy Chapter

pg_dump "postgresql://user:password@host:5432/rivet" --format=custom --file=rivet-$(date +%F).dump

pg_restore --dbname="postgresql://user:password@host:5432/rivet" --clean --if-exists rivet-2026-01-01.dump

# Stop the control plane first
tar czf rivet-data-$(date +%F).tar.gz -C /var/lib/rivet data

Test the restore Copy Chapter

A backup you have never restored is not a backup. Restore into a scratch environment on a schedule and confirm:

1. The control plane starts and reports healthy on /health.
2. The dashboard loads and your namespaces are present.
3. A worker connects and appears under Runners.
4. An actor created before the backup still resolves and reads its state.

Next steps Copy Chapter

• Storage backends
• Upgrades
• Production checklist

File: src/content/self-host/control-plane/configuration.mdx Copy Chapter

title: "Configuration" Copy Chapter

import EngineConfigSchema from "@/components/docs/EngineConfigSchemaClient.astro";

The control plane is the Rivet Engine. It reads configuration from files, from environment variables, or from both.

Configuration sources Copy Chapter

The engine accepts JSON, JSON5, JSONC, YAML, and YML, plus environment variables.

Environment variables Copy Section

Prefix a setting with RIVET__ and separate each level of nesting with __. Names are case-insensitive. To set postgres.url:

RIVET__POSTGRES__URL="postgresql://user:password@host:5432/database"

Configuration files Copy Section

Files are discovered automatically in a platform-specific directory:

Multiple files in the same directory are merged. /etc/rivet/config.json and /etc/rivet/database.json are loaded together.

Override the search path with --config:

# Load from a specific file
rivet-engine --config /path/to/config.json

# Load from a directory
rivet-engine --config /etc/rivet

# Load multiple paths, merged in order
rivet-engine --config /etc/rivet/base.json --config /etc/rivet/override.json

Reference Copy Chapter

{
	"pegboard": {
		"envoy_load_balancer": {
			"hash": {
				"virtual_nodes": 8,
				"samples": 2,
				"max_scan": 16,
				"use_snapshot_read": true
			}
		}
	}
}

openssl rand -hex 32

docker run -d \
  --restart unless-stopped \
  -p 6420:6420 \
  -p 6421:6421 \
  -v rivet-data:/data \
  -e RIVET__FILE_SYSTEM__PATH="/data" \
  -e RIVET__AUTH__ADMIN_TOKEN="<your-token>" \
  rivetdev/engine:2.3.3

curl -i http://<host>:6421/health

curl -X PUT "http://<host>:6420/runner-configs/default?namespace=default" \
  -H "Authorization: Bearer $RIVET_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"datacenters":{"default":{"normal":{}}}}'

RIVET_ENDPOINT="https://default:<admin-token>@your-control-plane.example.com"

services:
  rivet-engine:
    image: rivetdev/engine:latest
    ports:
      - "6420:6420"
    volumes:
      - rivet-data:/data
    environment:
      RIVET__FILE_SYSTEM__PATH: "/data"
      RIVET__AUTH__ADMIN_TOKEN: "${RIVET_ADMIN_TOKEN}"
    restart: unless-stopped

volumes:
  rivet-data:

echo "RIVET_ADMIN_TOKEN=$(openssl rand -hex 32)" >> .env

docker compose up -d

curl -i http://localhost:6420/health

curl -X PUT "http://localhost:6420/runner-configs/default?namespace=default" \
  -H "Authorization: Bearer $RIVET_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"datacenters":{"default":{"normal":{}}}}'

my-app:
    build: .
    environment:
      RIVET_ENDPOINT: "http://default:${RIVET_ADMIN_TOKEN}@rivet-engine:6420"
    depends_on:
      - rivet-engine
    restart: unless-stopped

docker compose up -d

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: rivet
      POSTGRES_USER: rivet
      POSTGRES_PASSWORD: rivet_password
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U rivet -d rivet"]
      interval: 5s
      timeout: 5s
      retries: 12
    restart: unless-stopped

  rivet-engine:
    image: rivetdev/engine:latest
    ports:
      - "6420:6420"
    environment:
      RIVET__POSTGRES__URL: postgresql://rivet:rivet_password@postgres:5432/rivet
      RIVET__AUTH__ADMIN_TOKEN: "${RIVET_ADMIN_TOKEN}"
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

volumes:
  postgres-data:

volumes:
      - ./rivet-config.json:/etc/rivet/config.json:ro
      - rivet-data:/data

pnpm install
pnpm assemble   # link each product's docs bundle
pnpm dev

FROM node:24-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
CMD ["node", "src/server.js"]

npx @rivetkit/cli deploy --token cloud_api_xxxxx

curl -s "$CLOUD_API_URL/projects/$PROJECT/namespaces/$CLOUD_NAMESPACE/managed-pools/default?org=$ORG" -H "Authorization: Bearer $CLOUD_TOKEN"

npx @rivetkit/cli setup-ci

gh secret set RIVET_CLOUD_TOKEN

npx @rivetkit/cli logs

npx @rivetkit/cli logs --follow

2026-06-16T18:26:51.160Z [INFO] eu-central-1 server listening on port 3000
2026-06-17T11:24:20.425Z [ERROR] us-east-1 failed to connect to upstream

# Last 200 lines from a specific namespace
npx @rivetkit/cli logs --namespace production -n 200

# A specific compute pool
npx @rivetkit/cli logs --pool my-pool

# Live tail, filtered
npx @rivetkit/cli logs --follow --contains error

# JSON, piped to jq
npx @rivetkit/cli logs -n 50 --json | jq .

npx @rivetkit/cli setup-ci
gh secret set RIVET_CLOUD_TOKEN

name: Rivet Preview

on:
  pull_request:
    types: [opened, synchronize, reopened]
  push:
    branches: [main]

concurrency:
  group: rivet-preview-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

jobs:
  rivet-preview:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: rivet-dev/preview-namespace-action@v1
        with:
          platform: vercel
          rivet-token: ${{ secrets.RIVET_CLOUD_TOKEN }}
          vercel-token: ${{ secrets.VERCEL_TOKEN }}

pnpm add @rivet-gg/icons

import { Icon, faCheckCircle } from "@rivet-gg/icons";

aws secretsmanager create-secret \
  --name rivet/admin-token \
  --secret-string "$(openssl rand -hex 32)"

{
  "family": "rivet-engine",
  "requiresCompatibilities": ["FARGATE"],
  "networkMode": "awsvpc",
  "cpu": "1024",
  "memory": "2048",
  "containerDefinitions": [
    {
      "name": "rivet-engine",
      "image": "rivetdev/engine:2.3.3",
      "portMappings": [
        { "containerPort": 6420 },
        { "containerPort": 6421 }
      ],
      "environment": [
        { "name": "RIVET__FILE_SYSTEM__PATH", "value": "/data" }
      ],
      "secrets": [
        {
          "name": "RIVET__AUTH__ADMIN_TOKEN",
          "valueFrom": "arn:aws:secretsmanager:REGION:ACCOUNT:secret:rivet/admin-token"
        }
      ],
      "mountPoints": [
        { "sourceVolume": "rivet-data", "containerPath": "/data" }
      ]
    }
  ],
  "volumes": [
    {
      "name": "rivet-data",
      "efsVolumeConfiguration": { "fileSystemId": "fs-XXXXXXXX" }
    }
  ]
}

aws elbv2 modify-load-balancer-attributes \
  --load-balancer-arn <arn> \
  --attributes Key=idle_timeout.timeout_seconds,Value=3600

aws ecs describe-services --cluster <cluster> --services rivet-engine \
  --query 'services[0].deployments[0].rolloutState'

curl -X PUT "http://<load-balancer-host>/runner-configs/default?namespace=default" \
  -H "Authorization: Bearer $RIVET_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"datacenters":{"default":{"normal":{}}}}'

pg_dump "postgresql://user:password@host:5432/rivet" --format=custom --file=rivet-$(date +%F).dump

pg_restore --dbname="postgresql://user:password@host:5432/rivet" --clean --if-exists rivet-2026-01-01.dump

# Stop the control plane first
tar czf rivet-data-$(date +%F).tar.gz -C /var/lib/rivet data

RIVET__POSTGRES__URL="postgresql://user:password@host:5432/database"

# Load from a specific file
rivet-engine --config /path/to/config.json

# Load from a directory
rivet-engine --config /etc/rivet

# Load multiple paths, merged in order
rivet-engine --config /etc/rivet/base.json --config /etc/rivet/override.json

{
	"pegboard": {
		"envoy_load_balancer": {
			"hash": {
				"virtual_nodes": 8,
				"samples": 2,
				"max_scan": 16,
				"use_snapshot_read": true
			}
		}
	}
}

openssl rand -hex 32

docker run -d \
  --restart unless-stopped \
  -p 6420:6420 \
  -p 6421:6421 \
  -v rivet-data:/data \
  -e RIVET__FILE_SYSTEM__PATH="/data" \
  -e RIVET__AUTH__ADMIN_TOKEN="<your-token>" \
  rivetdev/engine:2.3.3

curl -i http://<host>:6421/health

curl -X PUT "http://<host>:6420/runner-configs/default?namespace=default" \
  -H "Authorization: Bearer $RIVET_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"datacenters":{"default":{"normal":{}}}}'

RIVET_ENDPOINT="https://default:<admin-token>@your-control-plane.example.com"

services:
  rivet-engine:
    image: rivetdev/engine:latest
    ports:
      - "6420:6420"
    volumes:
      - rivet-data:/data
    environment:
      RIVET__FILE_SYSTEM__PATH: "/data"
      RIVET__AUTH__ADMIN_TOKEN: "${RIVET_ADMIN_TOKEN}"
    restart: unless-stopped

volumes:
  rivet-data:

echo "RIVET_ADMIN_TOKEN=$(openssl rand -hex 32)" >> .env

docker compose up -d

curl -i http://localhost:6420/health

curl -X PUT "http://localhost:6420/runner-configs/default?namespace=default" \
  -H "Authorization: Bearer $RIVET_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"datacenters":{"default":{"normal":{}}}}'

my-app:
    build: .
    environment:
      RIVET_ENDPOINT: "http://default:${RIVET_ADMIN_TOKEN}@rivet-engine:6420"
    depends_on:
      - rivet-engine
    restart: unless-stopped

docker compose up -d

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: rivet
      POSTGRES_USER: rivet
      POSTGRES_PASSWORD: rivet_password
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U rivet -d rivet"]
      interval: 5s
      timeout: 5s
      retries: 12
    restart: unless-stopped

  rivet-engine:
    image: rivetdev/engine:latest
    ports:
      - "6420:6420"
    environment:
      RIVET__POSTGRES__URL: postgresql://rivet:rivet_password@postgres:5432/rivet
      RIVET__AUTH__ADMIN_TOKEN: "${RIVET_ADMIN_TOKEN}"
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

volumes:
  postgres-data:

volumes:
      - ./rivet-config.json:/etc/rivet/config.json:ro
      - rivet-data:/data