Configuration

Registry Configuration

This page documents the configuration options available when setting up a RivetKit registry. The registry configuration is passed to the setup() function.

Example Configurations

Basic Setup

import { setup, actor } from "rivetkit";

const myActor = actor({ /* ... */ });

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

TypeScript

Connecting to Rivet Engine

import { setup, actor } from "rivetkit";

const myActor = actor({ /* ... */ });

// Reads from RIVET_ENDPOINT, RIVET_TOKEN, and RIVET_NAMESPACE
const registry = setup({
  use: { myActor },
});

Environment Variables

import { setup, actor } from "rivetkit";

const myActor = actor({ /* ... */ });

const registry = setup({
  use: { myActor },
  endpoint: "https://api.rivet.dev",
  token: process.env.RIVET_TOKEN,
  namespace: "production",
});

Config

Starting Your App

After configuring your registry, start it using one of two runtime modes:

import { registry } from "./actors";

export default registry.serve();

Serverless

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

const app = new Hono();
app.all("/api/rivet/*", (c) => registry.handler(c.req.raw));

export default app;

Serverless with Router

import { registry } from "./actors";

registry.startRunner();

Runner

See Runtime Modes for details on when to use each mode.

Environment Variables

Many configuration options can be set via environment variables. See Environment Variables for a complete reference.

Configuration Reference

use
map
Actor definitions. Keys are actor names, values are actor definitions.
maxIncomingMessageSize
nullable number
Maximum size of incoming WebSocket messages in bytes. Default: 65536
maxOutgoingMessageSize
nullable number
Maximum size of outgoing WebSocket messages in bytes. Default: 1048576
noWelcome
nullable boolean
Disable the welcome message on startup. Default: false
logging
nullable object
Logging configuration.
- logging.level
  nullable string
  Log level for RivetKit. Default: 'warn'
  - trace
  - debug
  - info
  - warn
  - error
  - fatal
  - silent
endpoint
nullable string
Endpoint URL to connect to Rivet Engine. Supports URL auth syntax: https://namespace:token@api.rivet.dev. Can also be set via RIVET_ENDPOINT environment variable.
token
nullable string
Authentication token for Rivet Engine. Can also be set via RIVET_TOKEN environment variable.
namespace
nullable string
Namespace to use. Default: 'default'. Can also be set via RIVET_NAMESPACE environment variable.
headers
nullable map
Additional headers to include in requests to Rivet Engine.
serveManager
nullable boolean
Whether to start the local manager server. Auto-determined based on endpoint and NODE_ENV if not specified.
managerBasePath
nullable string
Base path for the manager API. Default: '/'
managerPort
nullable number
Port to run the manager on. Default: 6420
inspector
nullable object
Inspector configuration for debugging and development.
- inspector.enabled
  nullable boolean
  Whether to enable the Rivet Inspector. Defaults to true in development mode.
- inspector.token
  nullable string
  Token used to access the Inspector.
- inspector.defaultEndpoint
  nullable string
  Default RivetKit server endpoint for Rivet Inspector to connect to.
serverless
nullable object
Configuration for serverless deployment mode.
- serverless.spawnEngine
  nullable boolean
  Downloads and starts the full Rust engine process. Auto-enabled in development mode when no endpoint is provided. Default: false
- serverless.engineVersion
  nullable string
  Version of the engine to download. Defaults to the current RivetKit version.
- serverless.configureRunnerPool
  nullable object
  Automatically configure serverless runners in the engine.
  - serverless.configureRunnerPool.name
    nullable string
    Name of the runner pool.
  - serverless.configureRunnerPool.url
    string
    URL of the serverless platform to configure runners.
  - serverless.configureRunnerPool.headers
    nullable map
    Headers to include in requests to the serverless platform.
  - serverless.configureRunnerPool.maxRunners
    nullable number
    Maximum number of runners in the pool.
  - serverless.configureRunnerPool.minRunners
    nullable number
    Minimum number of runners to keep warm.
  - serverless.configureRunnerPool.requestLifespan
    nullable number
    Maximum lifespan of a request in milliseconds.
  - serverless.configureRunnerPool.runnersMargin
    nullable number
    Buffer margin for scaling runners.
  - serverless.configureRunnerPool.slotsPerRunner
    nullable number
    Number of actor slots per runner.
  - serverless.configureRunnerPool.metadata
    nullable map
    Additional metadata to pass to the serverless platform.
- serverless.basePath
  nullable string
  Base path for serverless API routes. Default: '/api/rivet'
- serverless.publicEndpoint
  nullable string
  The endpoint that clients should connect to. Supports URL auth syntax: https://namespace:token@api.rivet.dev
- serverless.publicToken
  nullable string
  Token that clients should use when connecting via the public endpoint.
runner
nullable object
Configuration for runner mode.
- runner.totalSlots
  nullable number
  Total number of actor slots available. Default: 100000
- runner.runnerName
  nullable string
  Name of this runner. Default: 'default'
- runner.runnerKey
  nullable string
  Authentication key for the runner.
- runner.version
  nullable number
  Version number of this runner. Default: 1

Actor Configuration- Configure individual actors
HTTP Server Setup: Set up HTTP routing and middleware
Architecture: Understand how RivetKit works

Registry Configuration

Example Configurations

Basic Setup

Connecting to Rivet Engine

Starting Your App

Environment Variables

Configuration Reference

Related