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

Command Line

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.provision_users
  nullable map
  - clickhouse.provision_users[key].password
    string
  - clickhouse.provision_users[key].role
    string
    Admin
    Write
    ReadOnly
  - clickhouse.provision_users[key].username
    string
- clickhouse.secure
  nullable boolean
- clickhouse.username
  string
guard
nullable object
- guard.host
  nullable unknown
  Host for HTTP traffic
- 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
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_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.base_retry_timeout
  nullable unknown
  Time to delay an actor from rescheduling after a rescheduling failure. Unit is in milliseconds. **Experimental**
- pegboard.hibernating_request_eligible_threshold
  nullable unknown
  How long after last ping before considering a hibernating request disconnected. 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_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.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.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_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_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.
vector_http
nullable object
- vector_http.host
  string
- vector_http.port
  integer
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.unstable_disable_lock_customization
  nullable boolean
  UNSTABLE: Disable lock timeout customization When `false` (default), the driver sets `lock_timeout = '0'` and `deadlock_timeout = '10ms'` during transaction commits to optimize conflict detection. When `true`, these settings are NOT applied, which may be necessary for some PostgreSQL configurations or hosted services that don't support these settings. **This is an unstable feature and may change or be removed in future versions.**
- 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