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({ state: {}, actions: {} });

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

Connecting to Rivet Engine

import { setup, actor } from "rivetkit";

const myActor = actor({ state: {}, actions: {} });

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

import { setup, actor } from "rivetkit";

const myActor = actor({ state: {}, actions: {} });

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

Starting Your App

After configuring your registry, start it:

import { actor, setup } from "rivetkit";

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

registry.start();

import { actor, setup } from "rivetkit";

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

export default registry.serve();

import { Hono } from "hono";
import { actor, setup } from "rivetkit";

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

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

export default app;

import { actor, setup } from "rivetkit";

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

registry.startEnvoy();

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.
staticDir
nullable string
Directory to serve static files from. When set, registry.start() serves static files alongside the actor API.
httpBasePath
nullable string
Base path for the local RivetKit API. Default: '/'
httpPort
nullable number
Port to run the local HTTP server on. Default: 6421
httpHost
nullable string
Host to bind the local HTTP server to.
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.
startEngine
nullable boolean
Starts the full Rust engine process locally. Default: false
engineVersion
nullable string
Version of the local engine package to use. Defaults to the current RivetKit version.
configurePool
nullable object
Automatically configure serverless runners in the engine.
- configurePool.name
  nullable string
  Name of the runner pool.
- configurePool.url
  string
  URL of the serverless platform to configure runners.
- configurePool.headers
  nullable map
  Headers to include in requests to the serverless platform.
- configurePool.requestLifespan
  nullable number
  Maximum lifespan of a request in seconds.
- configurePool.metadata
  nullable map
  Additional metadata to pass to the serverless platform.
- configurePool.metadataPollInterval
  nullable number
  Interval in milliseconds between metadata polls from the engine. Defaults to 10000 milliseconds (10 seconds).
- configurePool.drainOnVersionUpgrade
  nullable boolean
  Drain runners when a new version is deployed. Defaults to true.
serverless
nullable object
Configuration for serverless deployment mode.
- 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.
envoy
nullable object
Configuration for envoy mode.
- envoy.totalSlots
  nullable number
  Total number of actor slots available. Default: 100000
- envoy.poolName
  nullable string
  Name of this envoy pool. Default: 'default'
- envoy.envoyKey
  nullable string
  Deprecated. Authentication key for the envoy.
- envoy.version
  nullable number
  Version number of this envoy. Default: 1

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