Sign In
General

Configuration

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

Configuration

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

Definition

interface RivetConfig {
  // Authentication configuration
  auth?: {
    admin_token: string;
  };

  // HTTP/HTTPS traffic handling service
  guard?: {
    host?: string;              // Default: "::" (IPv6 unspecified)
    port?: number;              // Default: 6420
    https?: {
      port: number;
      tls: {
        actor_cert_path: string;
        actor_key_path: string;
        api_cert_path: string;
        api_key_path: string;
      };
    };
  };

  // Public API service configuration
  api_public?: {
    verbose_errors?: boolean;           // Default: true
    respect_forwarded_for?: boolean;    // Default: false
  };

  // Private API service configuration
  api_peer?: {
    host?: string;      // Default: "::" (IPv6 unspecified)
    port?: number;      // Default: 6421
  };

  // Actor orchestration configuration (experimental)
  pegboard?: {
    base_retry_timeout?: number;                      // Default: 2000 (ms)
    actor_start_threshold?: number;                   // Default: 30000 (ms)
    actor_stop_threshold?: number;                    // Default: 30000 (ms)
    retry_reset_duration?: number;                    // Default: 600000 (ms)
    reschedule_backoff_max_exponent?: number;         // Default: 8
    runner_eligible_threshold?: number;               // Default: 10000 (ms)
    runner_lost_threshold?: number;                   // Default: 15000 (ms)
    hibernating_request_eligible_threshold?: number;  // Default: 90000 (ms)
    serverless_base_retry_timeout?: number;           // Default: 2000 (ms)
    serverless_retry_reset_duration?: number;         // Default: 600000 (ms)
    serverless_backoff_max_exponent?: number;         // Default: 8
    pool_desired_max_override?: number;
  };

  // Logging configuration
  logs?: {
    redirect_logs_dir?: string;  // Directory for log file redirection
  };

  // Multi-datacenter topology
  topology?: {
    datacenter_label: number;     // Default: 1
    datacenters: Array<{
      name: string;               // Default: "default"
      datacenter_label: number;   // Default: 1
      is_leader: boolean;         // Default: true
      public_url: string;         // Default: "http://127.0.0.1:6420"
      peer_url: string;           // Default: "http://127.0.0.1:6421"
      proxy_url?: string;
      valid_hosts?: string[];     // Required when multiple datacenters configured
    }>;
  };

  // Database backend configuration
  database?:
    | {
        postgres: {
          url: string;  // Default: "postgresql://postgres:postgres@127.0.0.1:5432/postgres"
                        // Supports standard PostgreSQL connection parameters
                        // See SSL Configuration section below for details
          unstable_disable_lock_customization?: boolean;  // Default: false
                                                          // UNSTABLE: Required for some hosted platforms
                                                          // See Postgres Configuration section below
          ssl?: {
            root_cert_path?: string;
            client_cert_path?: string;
            client_key_path?: string;
          };
        };
      }
    | {
        file_system: {
          path: string;  // Default: "~/.local/share/rivet-engine/db" or "./data/db"
        };
      };

  // Message pub/sub system
  pubsub?:
    | {
        nats: {
          addresses: string[];       // Default: ["127.0.0.1:4222"]
          port?: number;            // Default: 4222
          username?: string;
          password?: string;
        };
      }
    | {
        postgres_notify: {
          url: string;  // Default: "postgresql://postgres:postgres@127.0.0.1:5432/postgres"
          memory_optimization?: boolean;  // Default: true
          ssl?: {
            root_cert_path?: string;
            client_cert_path?: string;
            client_key_path?: string;
          };
        };
      }
    | {
        memory: {
          channel: string;  // Default: "default"
        };
      };

  // Caching layer configuration
  cache?: {
    driver: "redis" | "in_memory";  // Default: "in_memory"
  };

  // ClickHouse analytics database (optional)
  clickhouse?: {
    http_url: string;
    native_url: string;
    username: string;
    password?: string;
    secure?: boolean;  // Default: false
    provision_users?: {
      [key: string]: {
        username: string;
        password: string;
        role: "Admin" | "Write" | "ReadOnly";
      };
    };
  };

  // Vector HTTP endpoint (optional)
  vector_http?: {
    host: string;  // Default: "127.0.0.1"
    port: number;  // Default: 5022
  };

  // Telemetry configuration
  telemetry?: {
    enabled: boolean;  // Default: true (opt-out)
  };

  // Runtime configuration
  runtime?: {
    worker_cpu_max?: number;           // Worker CPU limit in millicores (1000 = 1 core)
    worker_shutdown_duration?: number; // Default: 30 (seconds)
    guard_shutdown_duration?: number;  // Default: 3600 (seconds)
    allow_version_rollback?: boolean;  // Default: false
  };
}
TypeScript

PostgreSQL Configuration

Managed Postgres Compatibility

Some hosted PostgreSQL platforms require additional configuration due to platform-specific restrictions.

Use direct connection (not connection pooler).

{
  "database": {
    "postgres": {
      "url": "postgresql://pscale_api_<username>.<unique-id>:<password>@<region>.pg.psdb.cloud:5432/postgres?sslmode=require",
      "unstable_disable_lock_customization": true
    }
  }
}

For better performance, set deadlock_timeout = 10ms in the PlanetScale dashboard at Clusters → Parameters → Query Tuning.

SSL/TLS Support

To enable SSL for Postgres, add sslmode=require to your PostgreSQL connection URL:

{
  "database": {
    "postgres": {
      "url": "postgresql://user:password@host.example.com:5432/database?sslmode=require"
    }
  }
}

The sslmode parameter controls TLS usage:

  • disable: Do not use TLS
  • prefer: Use TLS if available, otherwise connect without TLS (default)
  • require: Require TLS connection (fails if TLS is not available)

To verify the server certificate against a CA or verify the hostname, use custom SSL certificates (see below).

Custom SSL Certificates

For databases using custom certificate authorities (e.g., Supabase) or requiring client certificate authentication, you can specify certificate paths in the configuration:

{
  "database": {
    "postgres": {
      "url": "postgresql://user:password@host:5432/database?sslmode=require",
      "ssl": {
        "root_cert_path": "/path/to/root-ca.crt",
        "client_cert_path": "/path/to/client.crt",
        "client_key_path": "/path/to/client.key"
      }
    }
  }
}
ParameterDescriptionPostgreSQL Equivalent
root_cert_pathPath to the root certificate file for verifying the server's certificatesslrootcert
client_cert_pathPath to the client certificate file for client certificate authenticationsslcert
client_key_pathPath to the client private key file for client certificate authenticationsslkey

All SSL paths are optional. If not specified, Rivet uses the default system root certificates from Mozilla's root certificate store.

Do Not Use Connection Poolers

Rivet requires direct PostgreSQL connections for session-level features and does not support connection poolers.

Do not use:

  • PgBouncer
  • Supavisor
  • AWS RDS Proxy

Troubleshooting

Permission Denied Errors

If you see errors like:

ERROR: permission denied to set parameter "deadlock_timeout"
ERROR: current transaction is aborted, commands ignored until end of transaction block

Add unstable_disable_lock_customization: true to your configuration:

{
  "database": {
    "postgres": {
      "url": "postgresql://...",
      "unstable_disable_lock_customization": true
    }
  }
}
JSON

This disables Rivet's attempt to set lock_timeout = 0 and deadlock_timeout = 10ms. Since lock_timeout defaults to 0 in PostgreSQL, skipping these settings is safe. Deadlock detection will use the default 1s timeout instead of 10ms.

Suggest changes to this page