General

Configuration

Rivet Engine can be configured through environment variables or configuration files.

The full JSON Schema for the configuration is available at /docs/engine-config-schema.json.

Configuration Sources

Rivet supports JSON, JSON5, JSONC, YAML, YML, and environment variable configurations.

Environment Variables

Use the RIVET__ prefix with __ as separator to configure properties in the config. For example: set the RIVET__database__postgres__url environment variable for database.postgres.url.

Configuration Paths

Configuration files are automatically discovered in platform-specific directories:

Linux: /etc/rivet/config.json
macOS: /Library/Application Support/rivet/config.json
Windows: C:\ProgramData\rivet\config.json

Multiple Files

Multiple configuration files in the same directory are loaded and merged together. For example: /etc/rivet/config.json and /etc/rivet/database.json will be merged together.

Override Configuration Path

You can override the default configuration path using the --config flag:

# 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

Configuration Reference

api_peer
nullable object
Configuration for the private API service.
- api_peer.host
  nullable unknown
- api_peer.port
  nullable unknown
api_public
nullable object
Configuration for the public API service.
- api_public.respect_forwarded_for
  nullable unknown
  Flag to respect the X-Forwarded-For header for client IP addresses. Will be ignored in favor of CF-Connecting-IP if DNS provider is configured as Cloudflare.
- api_public.verbose_errors
  nullable unknown
  Flag to enable verbose error reporting.
auth
nullable object
- auth.admin_token
  string
cache
nullable object
Configuration for the cache layer.
- cache.driver
  string
  - redis
  - in_memory
clickhouse
nullable object
- clickhouse.http_url
  string
  URL to the HTTP access port for ClickHouse.
- clickhouse.native_url
  string
  URL to the native access port for ClickHouse.
- clickhouse.password
  nullable string
- clickhouse.secure
  nullable boolean
- clickhouse.username
  string
guard
nullable object
- guard.host
  nullable unknown
  Host for HTTP traffic
- guard.http_max_request_body_size
  nullable unknown
  Max HTTP request body size in bytes (first line of defense).
- guard.https
  nullable object
  - guard.https.port
    integer
  - guard.https.tls
    object
    guard.https.tls.actor_cert_path
    string
    guard.https.tls.actor_key_path
    string
    guard.https.tls.api_cert_path
    string
    guard.https.tls.api_key_path
    string
- guard.port
  nullable unknown
  Port for HTTP traffic
- guard.proxy_state_cache_ttl_ms
  nullable unknown
  Proxy state cache TTL in milliseconds.
- guard.route_cache_ttl_ms
  nullable unknown
  Route cache TTL in milliseconds.
- guard.websocket_close_linger_ms
  nullable unknown
  Time to keep TCP connection open after WebSocket close, in milliseconds.
- guard.websocket_max_message_size
  nullable unknown
  Max incoming WebSocket message size in bytes.
- guard.websocket_max_outgoing_message_size
  nullable unknown
  Max outgoing WebSocket message size in bytes.
logs
nullable object
- logs.redirect_logs_dir
  nullable unknown
metrics
nullable object
Configuration for the metrics service.
- metrics.host
  nullable unknown
- metrics.port
  nullable unknown
pegboard
nullable object
- pegboard.actor_allocation_candidate_sample_size
  nullable unknown
  Amount of runners to query from the allocation queue and choose at random when allocating an actor. **Experimental**
- pegboard.actor_start_threshold
  nullable unknown
  How long to wait after creating and not receiving a starting state before setting actor as lost. Unit is in milliseconds. **Experimental**
- pegboard.actor_stop_threshold
  nullable unknown
  How long to wait after stopping and not receiving a stop state before setting actor as lost. Unit is in milliseconds. **Experimental**
- pegboard.api_max_http_request_body_size
  nullable unknown
  Max HTTP request body size in bytes for API traffic.
- pegboard.api_max_in_flight
  nullable unknown
  Maximum concurrent in-flight requests for API traffic.
- pegboard.api_rate_limit_period_secs
  nullable unknown
  Rate limit for API traffic: period in seconds.
- pegboard.api_rate_limit_requests
  nullable unknown
  Rate limit for API traffic: number of requests allowed per period.
- pegboard.api_retry_initial_interval_ms
  nullable unknown
  Initial retry interval for API traffic in milliseconds.
- pegboard.api_retry_max_attempts
  nullable unknown
  Maximum retry attempts for API traffic.
- pegboard.base_retry_timeout
  nullable unknown
  Time to delay an actor from rescheduling after a rescheduling failure. Unit is in milliseconds. **Experimental**
- pegboard.default_metadata_poll_interval
  nullable unknown
  Default metadata poll interval for serverless runners when not specified in runner config. Unit is in milliseconds. **Experimental**
- pegboard.gateway_actor_request_timeout_secs
  nullable unknown
  HTTP request timeout in seconds for actor traffic. This is the outer timeout for the entire request lifecycle. Should be slightly longer than `gateway_response_start_timeout_ms` to provide a grace period.
- pegboard.gateway_api_request_timeout_secs
  nullable unknown
  HTTP request timeout in seconds for API traffic (api-public).
- pegboard.gateway_gc_interval_ms
  nullable unknown
  GC interval for in-flight requests in milliseconds.
- pegboard.gateway_http_max_request_body_size
  nullable unknown
  Max HTTP request body size in bytes for requests to actors. Note: guard-core also enforces a larger limit (default 256 MiB) as a first line of defense. See `Guard::http_max_request_body_size`.
- pegboard.gateway_hws_max_pending_size
  nullable unknown
  Max pending message buffer size for hibernating WebSockets in bytes.
- pegboard.gateway_hws_message_ack_timeout_ms
  nullable unknown
  Hibernating WebSocket message ack timeout in milliseconds.
- pegboard.gateway_max_in_flight
  nullable unknown
  Maximum concurrent in-flight requests per actor per IP.
- pegboard.gateway_rate_limit_period_secs
  nullable unknown
  Rate limit: period in seconds.
- pegboard.gateway_rate_limit_requests
  nullable unknown
  Rate limit: number of requests allowed per period.
- pegboard.gateway_response_start_timeout_ms
  nullable unknown
  Timeout for response to start in milliseconds.
- pegboard.gateway_retry_initial_interval_ms
  nullable unknown
  Initial retry interval in milliseconds (doubles with each attempt).
- pegboard.gateway_retry_max_attempts
  nullable unknown
  Maximum retry attempts for failed requests.
- pegboard.gateway_tunnel_ping_timeout_ms
  nullable unknown
  Tunnel ping timeout in milliseconds.
- pegboard.gateway_update_ping_interval_ms
  nullable unknown
  Ping interval for gateway updates in milliseconds.
- pegboard.gateway_websocket_open_timeout_ms
  nullable unknown
  WebSocket open/handshake timeout in milliseconds.
- pegboard.gateway_ws_connect_timeout_secs
  nullable unknown
  WebSocket connection attempt timeout in seconds.
- pegboard.gateway_ws_flush_timeout_secs
  nullable unknown
  WebSocket flush timeout in seconds.
- pegboard.gateway_ws_proxy_timeout_secs
  nullable unknown
  WebSocket proxy task timeout in seconds.
- pegboard.gateway_ws_send_timeout_secs
  nullable unknown
  WebSocket send message timeout in seconds.
- pegboard.hibernating_request_eligible_threshold
  nullable unknown
  How long after last ping before considering a hibernating request disconnected. Unit is in milliseconds. **Experimental**
- pegboard.min_metadata_poll_interval
  nullable unknown
  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. **Experimental**
- pegboard.pool_desired_max_override
  nullable unknown
  Global pool desired max.
- pegboard.reschedule_backoff_max_exponent
  nullable unknown
  Maximum exponent for the reschedule backoff calculation. This controls the maximum backoff duration when rescheduling actors. **Experimental**
- pegboard.retry_reset_duration
  nullable unknown
  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. **Experimental**
- pegboard.runner_eligible_threshold
  nullable unknown
  How long after last ping before considering a runner ineligible for allocation. Unit is in milliseconds. **Experimental**
- pegboard.runner_event_demuxer_gc_interval_ms
  nullable unknown
  GC interval for actor event demuxer in milliseconds.
- pegboard.runner_event_demuxer_max_last_seen_ms
  nullable unknown
  Max time since last seen before actor is considered stale, in milliseconds.
- pegboard.runner_http_max_response_body_size
  nullable unknown
  Max HTTP response body size in bytes from actors.
- pegboard.runner_lost_threshold
  nullable unknown
  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. **Experimental**
- pegboard.runner_pool_consecutive_successes_to_clear_error
  nullable unknown
  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. **Experimental**
- pegboard.runner_update_ping_interval_ms
  nullable unknown
  Ping interval for runner updates in milliseconds.
- pegboard.serverless_backoff_max_exponent
  nullable unknown
  Maximum exponent for the serverless backoff calculation. This controls the maximum backoff duration when serverlessly connecting to runners. **Experimental**
- pegboard.serverless_base_retry_timeout
  nullable unknown
  Time to delay a serverless runner from attempting a new outbound connection after a connection failure. Unit is in milliseconds. **Experimental**
- pegboard.serverless_retry_reset_duration
  nullable unknown
  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. **Experimental**
runtime
nullable object
- runtime.allow_version_rollback
  nullable unknown
  Whether or not to allow running the engine when the previous version that was run is higher than the current version.
- runtime.force_shutdown_duration
  nullable unknown
  Time (in seconds) after which the engine process will forcibly exit after receiving SIGTERM. Must be greater than both worker_shutdown_duration and guard_shutdown_duration. Defaults to guard_shutdown_duration + 30 seconds.
- runtime.gasoline
  nullable object
  - runtime.gasoline.prune_eligibility_duration
    nullable unknown
    Time (in seconds) after completion before considering a workflow eligible for pruning. Defaults to 7 days. Set to 0 to never prune workflow data.
  - runtime.gasoline.prune_interval_duration
    nullable unknown
    Time (in seconds) to periodically check for workflows to prune. Defaults to 12 hours.
- runtime.guard_shutdown_duration
  nullable unknown
  Time (in seconds) to allow for guard to wait for pending requests after receiving SIGTERM. Defaults to 1 hour.
- runtime.worker
  nullable object
  - runtime.worker.cpu_max
    nullable unknown
    Adjusts worker curve around this value (in millicores, 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.
  - runtime.worker.load_shedding_curve
    nullable unknown
    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 (permilli overall cpu usage, permilli) Default: | . . 100% | _____ . | .\ . % wfs | . \ . | . \. 5% | . \_____ |_____.___.______ 0 60% 80% avg cpu usage
  - runtime.worker.shutdown_duration
    nullable unknown
    Time (in seconds) to allow for the gasoline worker engine to stop gracefully after receiving SIGTERM. Defaults to 30 seconds.
telemetry
nullable object
- telemetry.enabled
  boolean
topology
nullable object
- topology.datacenter_label
  integer
  Must be included in `datacenters`
- topology.datacenters
  array of objects
  List of all datacenters, including this datacenter.
  - topology.datacenters[].datacenter_label
    integer
  - topology.datacenters[].is_leader
    boolean
  - topology.datacenters[].name
    string
  - topology.datacenters[].peer_url
    string
    URL of the api-peer service
  - topology.datacenters[].proxy_url
    nullable unknown
    URL of the guard service that other datacenters can access privately. Goes to the same place as
  - topology.datacenters[].public_url
    string
    Public origin that can be used to connect to this region.
  - topology.datacenters[].valid_hosts
    nullable unknown
    List of hosts that are valid to connect to this region with. This is used in regional endpoints to validate that incoming requests to this datacenter are going to a region-specific domain. IMPORTANT: Do not use a global origin that routes to multiple different regions. This will cause unpredictable behavior when requests are expected to go to a specific region.
postgres
nullable object
- postgres.ssl
  nullable object
  - postgres.ssl.client_cert_path
    nullable unknown
    Path to the client certificate file Used for client certificate authentication Equivalent to PostgreSQL's `sslcert` parameter
  - postgres.ssl.client_key_path
    nullable unknown
    Path to the client private key file Used for client certificate authentication Equivalent to PostgreSQL's `sslkey` parameter
  - postgres.ssl.root_cert_path
    nullable unknown
    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
- postgres.url
  string
file_system
nullable object
- file_system.path
  string

PostgreSQL: Configure PostgreSQL for production
File System: Configure file system storage for development

Configuration

Configuration Sources

Configuration Reference

Related