Configuration

Actor Configuration

This page documents the configuration options available when defining a RivetKit actor. The actor configuration is passed to the `actor()` function.

Basic Example

import { actor, setup } from "rivetkit";

const myActor = actor({
  state: { count: 0 },

  actions: {
    increment: (c) => {
      c.state.count++;
      return c.state.count;
    },
  },
  options: {
    actionTimeout: 15_000,
  }
});

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

Configuration Reference

state
nullable unknown
Initial state value for the actor. Cannot be used with createState.
createState
nullable unknown
Function to create initial state. Receives context and input. Cannot be used with state.
connState
nullable unknown
Initial connection state value. Cannot be used with createConnState.
createConnState
nullable unknown
Function to create connection state. Receives context and connection params. The pending connection is not visible in c.conns until this succeeds. Cannot be used with connState.
vars
nullable unknown
Initial ephemeral variables value. Cannot be used with createVars.
createVars
nullable unknown
Function to create ephemeral variables. Receives context and driver context. Cannot be used with vars.
db
nullable unknown
Database provider instance for the actor.
onCreate
nullable unknown
Called when the actor is first initialized. Use to initialize state.
onDestroy
nullable unknown
Called when the actor is destroyed.
onMigrate
nullable unknown
Called on every actor start after persisted state loads and before onWake. Use for repeatable schema migrations.
onWake
nullable unknown
Called when the actor wakes up and is ready to receive connections and actions.
onSleep
nullable unknown
Called when the actor is stopping or sleeping. Use to clean up resources.
run
nullable unknown
Called after actor starts. Does not block startup. Use for background tasks like queue processing or tick loops. If it exits, the actor follows the normal idle sleep timeout once idle. If it throws, the actor logs the error and then follows the normal idle sleep timeout once idle.
onStateChange
nullable unknown
Called when the actor's state changes. State changes within this hook won't trigger recursion.
onBeforeConnect
nullable unknown
Called before a client connects. Throw an error to reject the connection. The pending connection is not visible in c.conns while this runs.
onConnect
nullable unknown
Called when a client successfully connects. The connection is visible in c.conns before this runs.
onDisconnect
nullable unknown
Called when a client disconnects.
onBeforeActionResponse
nullable unknown
Called before sending an action response. Use to transform output.
onRequest
nullable unknown
Called for raw HTTP requests to /actors/{name}/http/* endpoints.
onWebSocket
nullable unknown
Called for raw WebSocket connections to /actors/{name}/websocket/* endpoints.
actions
nullable map
Map of action name to handler function. Defaults to an empty object.
actionInputSchemas
nullable map
Optional schema map for validating action argument tuples in native runtimes.
connParamsSchema
nullable unknown
Optional schema for validating connection params in native runtimes.
events
nullable map
Map of event names to schemas.
queues
nullable map
Map of queue names to schemas.
options
nullable object
Actor options for timeouts and behavior configuration.
- options.name
  nullable string
  Display name for the actor in the Inspector UI.
- options.icon
  nullable string
  Icon for the actor in the Inspector UI. Can be an emoji (e.g., '🚀') or FontAwesome icon name (e.g., 'rocket').
- options.enableActorRuntimeSocket
  nullable boolean
  Enables the experimental Actor Runtime Socket for this actor. Default: false
- options.createVarsTimeout
  nullable number
  Timeout in ms for createVars handler. Default: 5000
- options.createConnStateTimeout
  nullable number
  Timeout in ms for createConnState handler. Default: 5000
- options.onMigrateTimeout
  nullable number
  Timeout in ms for onMigrate handler. Default: 30000
- options.onBeforeConnectTimeout
  nullable number
  Timeout in ms for onBeforeConnect handler. Default: 5000
- options.onConnectTimeout
  nullable number
  Timeout in ms for onConnect handler. Default: 5000
- options.sleepGracePeriod
  nullable number
  Max time in ms for the graceful shutdown window. Covers lifecycle hooks (onSleep, onDestroy), the run handler wait, async raw WebSocket handlers, disconnect callbacks, and final state serialization. Default: 15000.
- options.onDestroyTimeout
  nullable number
  Deprecated. Folded into sleepGracePeriod, which now bounds the entire graceful shutdown window for both sleep and destroy. Will be removed in 2.2.0.
- options.waitUntilTimeout
  nullable number
  Deprecated. Folded into sleepGracePeriod, which now bounds the entire graceful shutdown window for both sleep and destroy. Will be removed in 2.2.0.
- options.stateSaveInterval
  nullable number
  Interval in ms between automatic state saves. Default: 1000
- options.actionTimeout
  nullable number
  Timeout in ms for action handlers. Default: 60000
- options.connectionLivenessTimeout
  nullable number
  Timeout in ms for connection liveness checks. Default: 2500
- options.connectionLivenessInterval
  nullable number
  Interval in ms between connection liveness checks. Default: 5000
- options.noSleep
  nullable boolean
  Deprecated. If true, the actor will never sleep. Use c.keepAwake(promise) to scope keep-awake to a specific operation instead. Default: false
- options.sleepTimeout
  nullable number
  Time in ms of inactivity before the actor sleeps. Default: 30000
- options.maxQueueSize
  nullable number
  Maximum number of queue messages before rejecting new messages. Default: 1000
- options.maxQueueMessageSize
  nullable number
  Maximum size of each queue message in bytes. Default: 65536
- options.canHibernateWebSocket
  nullable boolean
  Whether WebSockets using onWebSocket can be hibernated. WebSockets using actions/events are hibernatable by default. Default: false

Registry Configuration: Configure the RivetKit registry
State: Managing actor state
Actions: Defining actor actions
Lifecycle: Actor lifecycle hooks

Actor Configuration

Basic Example

Configuration Reference

Related