Configuration
Every control plane setting, in one table. Guides link here instead of restating options.
The control plane is the Rivet Engine. It reads configuration from files, from environment variables, or from both.
Configuration sources
The engine accepts JSON, JSON5, JSONC, YAML, and YML, plus environment variables.
Environment variables
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
Files are discovered automatically in a platform-specific directory:
| Platform | Path |
|---|---|
| Linux | /etc/rivet/config.json |
| macOS | /Library/Application Support/rivet/config.json |
| Windows | C:\ProgramData\rivet\config.json |
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
Configuration for the private API service.
Configuration for the cache layer.
URL to the HTTP access port for ClickHouse.
URL to the native access port for ClickHouse.
Timeout sent with actor force-wake requests in milliseconds.
Timeout for waiting for an actor to become ready in milliseconds.
Enables the internal websocket health route for debug and latency testing. This is intended for websocket ping/pong verification and should remain disabled in normal deployments.
Host for HTTP traffic
Max HTTP request body size in bytes (first line of defense).
Port for HTTP traffic
Timeout for resolving api-public routes in milliseconds.
Timeout for guard-owned route authorization checks in milliseconds.
TTL for cached route lookups in milliseconds.
Timeout for resolving compute routes in milliseconds.
Timeout for dispatching to each guard routing module in milliseconds.
Timeout for pegboard actor route authorization checks in milliseconds.
Timeout for fetching pegboard actor routing state in milliseconds.
Timeout for resolving pegboard actor query routes in milliseconds.
Timeout for subscribing to pegboard actor routing events in milliseconds.
Timeout for sending pegboard actor wake signals in milliseconds.
Backstop timeout for route resolution in milliseconds. Primary timeout signals live inside each guard routing phase.
Enables TCP_NODELAY on accepted Guard sockets.
Enables W3C trace context propagation (extract from incoming requests, inject into upstream requests/websockets).
Max WebSocket frame size in bytes.
Max WebSocket message size in bytes.
Configuration for the metrics service.
Amount of runners to query from the allocation queue and choose at random when allocating an actor.
How long to wait for an ack response from the outbound request layer before setting actor as lost. Unit is in milliseconds.
Time to regain one actor creation token per namespace. Unit is in milliseconds.
Max burst of actor creations per namespace before throttling.
How long to wait after starting to attempt to reallocate before before setting actor to sleep. Unit is in milliseconds.
How long to wait after creating and not receiving a starting state before setting actor as lost. Unit is in milliseconds.
How long to wait after stopping and not receiving a stop state before setting actor as lost. Unit is in milliseconds.
Time to delay an actor from rescheduling after a rescheduling failure. Unit is in milliseconds.
Default metadata poll interval for serverless runners when not specified in runner config. Unit is in milliseconds.
How long after last ping before considering a envoy ineligible for allocation. Unit is in milliseconds.
GC interval for actor event demuxer in milliseconds.
Max time since last seen before actor is considered stale, in milliseconds.
Maximum concurrent background expire operations spawned by the read-path envoy expire scheduler.
Maximum pending envoys tracked by the read-path envoy expire scheduler.
Maximum stale entries walked per `scan_for_fresh` call before aborting and returning `None`. Circuit breaker against pathological drain scenarios. Default 16. Range 1..=256.
Number of independent ring samples per allocation. `1` = uniform pick (no slot read), `>= 2` = power-of-K-choices.
Additive random integer added to each candidate's slot count before the min-slot comparison. Decorrelates concurrent allocators reading the same stale `SlotsKey` snapshot. Only relevant when `samples >= 2`. `0` disables. Range 0..=64. Default 4. See `slot_jitter` block in `engine/packages/pegboard/src/workflows/actor2/alloc_serverful/hash.rs` for how the default was sized.
How long to wait before considering an envoy lost and evicting all of its actors. Unit is in milliseconds.
Max response payload size in bytes from actors.
Max time since last pong before the envoy connection is terminated. Unit is in milliseconds.
Ping interval for envoy updates in milliseconds.
Time to regain one inbound WebSocket message token on a single envoy connection. Unit is in microseconds. The envoy connection multiplexes every actor on a runner, so the sustained ceiling is far higher than the per-client gateway limit and needs sub-millisecond granularity to express.
Max burst of inbound WebSocket messages on a single envoy connection before throttling.
GC interval for in-flight requests in milliseconds.
Max HTTP request body size in bytes for requests to actors.
Max pending message buffer size for hibernating WebSockets in bytes.
Hibernating WebSocket message ack timeout in milliseconds.
Timeout for response to start in milliseconds.
Tunnel ping timeout in milliseconds.
Ping interval for gateway updates in milliseconds.
WebSocket open/handshake timeout in milliseconds.
Time to regain one inbound WebSocket message token on a single connection. Unit is in milliseconds.
Max burst of inbound WebSocket messages on a single connection before throttling.
How long after last ping before considering a hibernating request disconnected. Unit is in milliseconds.
Minimum metadata poll interval for serverless runners. The actual poll interval will be the maximum of this value and the runner config's `metadata_poll_interval` setting. This prevents excessive polling even if the runner config specifies a very short interval. Unit is in milliseconds.
Global pool desired max.
Maximum total size of all preloaded KV data sent with the actor start command. Setting to 0 disables all preloading. Unit is in bytes. Default: 1,048,576 (1 MiB).
Maximum exponent for the reschedule backoff calculation. This controls the maximum backoff duration when rescheduling actors.
How long an actor goes without retries before it's retry count is reset to 0, effectively resetting its backoff to 0. Unit is in milliseconds.
How long after last ping before considering a runner ineligible for allocation. Unit is in milliseconds.
GC interval for actor event demuxer in milliseconds.
Max time since last seen before actor is considered stale, in milliseconds.
How long to wait after last ping before forcibly removing a runner from the database and deleting its workflow, evicting all actors. Note that the runner may still be running and can reconnect. Unit is in milliseconds.
Max response payload size in bytes from actors.
Max time since last pong before the runner connection is terminated. Unit is in milliseconds.
Number of consecutive successes required to clear an active runner pool error. This prevents a single success from clearing an error during flapping conditions. Higher values provide more stability but slower recovery from transient errors.
Ping interval for runner updates in milliseconds.
Maximum exponent for the serverless backoff calculation. This controls the maximum backoff duration when serverlessly connecting to runners.
Time to delay a serverless runner from attempting a new outbound connection after a connection failure. Unit is in milliseconds.
**Deprecated** Configure the drain period in the runner config. Drain grace period for serverless runners. This time is subtracted from the configured request duration. Once `duration - grace` is reached, the runner is sent stop commands for all of its actors. After the grace period is over (i.e. the full duration is reached) the runner websocket is forcibly closed. Unit is in milliseconds.
How long a serverless runner goes without connection failures before it's retry count is reset to 0, effectively resetting its backoff to 0. Unit is in milliseconds.
Sampling frequency in Hz.
Base URL of the Pyroscope server profiles are pushed to. Presence of this block means profiling is available; the profiler itself is toggled at runtime via the `profile enable`/`profile disable` CLI and starts off.
Whether or not to allow running the engine when the previous version that was run is higher than the current version.
Time (in seconds) after which the engine process will forcibly exit after receiving SIGTERM. Must be greater than or equal to both worker_shutdown_duration and guard_shutdown_duration. Defaults to 10 minutes.
Time (in seconds) after completion before considering a workflow eligible for pruning. Defaults to 7 days. Set to 0 to never prune workflow data.
Time (in seconds) to periodically check for workflows to prune. Defaults to 12 hours.
Time (in seconds) to allow for guard to wait for pending requests after receiving SIGTERM. Defaults to 10 minutes.
Adjusts worker curve around this value (in millecores, i.e. 1000 = 1 core). Is not a hard limit. When unset, uses /sys/fs/cgroup/cpu.max, and if that is unset uses total host cpu.
Exponential moving average beta term. Defaults to 0.95.
Determine load shedding ratio based on linear mapping on cpu usage. We will gradually pull less workflows as the cpu usage increases. Units are in (permille overall cpu usage, permille) Default: | . . 100% | _____ . | .\ . % wfs | . \ . | . \. 5% | . \_____ |_____.___.______ 0 70% 90% avg cpu usage
Time (in seconds) to allow for the gasoline worker engine to stop gracefully after receiving SIGTERM. Defaults to 30 seconds.
UNSTABLE: disables the SQLite v2 commit dirty-page size cap.
UNSTABLE: disables SQLite hot compaction.
Must be included in `datacenters`
Capacity of the async-nats client command queue. When this fills, client operations such as subscribe, publish, and drain wait until the connection task catches up.
When true, force every UPS publish to round-trip through NATS instead of taking the in-process fast path for subjects that have a local subscriber on the same engine pod. Opt-in diagnostic; default false.
Capacity of each individual NATS subscriber message buffer. When this fills, async-nats drops the message and emits `SlowConsumer`. Rivet logs this as `nats slow consumer`.
Path to the client certificate file Used for client certificate authentication Equivalent to PostgreSQL's `sslcert` parameter
Path to the client private key file Used for client certificate authentication Equivalent to PostgreSQL's `sslkey` parameter
Path to the root certificate file for verifying the server's certificate Required when using custom certificate authorities (e.g., Supabase) Equivalent to PostgreSQL's `sslrootcert` parameter
Envoy load balancing
pegboard.envoy_load_balancer selects how actors are assigned to envoys. The hash strategy uses a hash ring:
{
"pegboard": {
"envoy_load_balancer": {
"hash": {
"virtual_nodes": 8,
"samples": 2,
"max_scan": 16,
"use_snapshot_read": true
}
}
}
}
Use samples: 1 for a uniform random pick that skips slot reads, or samples: 2 or higher for power-of-K choices over envoy slot counts. Treat virtual_nodes as an operational invariant once envoys have registered: changing it reshuffles the ring.
Telemetry
The engine exports traces and metrics over OpenTelemetry.
| Variable | Purpose | Default |
|---|---|---|
RIVET_OTEL_ENABLED | Set to 1 to enable export | off |
RIVET_OTEL_GRPC_ENDPOINT | Collector endpoint | http://localhost:4317 |
RIVET_OTEL_SAMPLER_RATIO | Trace sampling ratio | 0.001 |