zopu-code/.agents/skills/ai-agent-workspace/reference/self-hosting/configuration.md

Configuration

Source: src/content/docs/self-hosting/configuration.mdx Canonical URL: https://rivet.dev/docs/self-hosting/configuration Description: 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

Pegboard Envoy Load Balancing

pegboard.envoy_load_balancer supports the hash strategy for hash-ring-based envoy selection:

{
	"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. Use samples >= 2 for power-of-K choices over envoy slot counts. Treat virtual_nodes as an operational invariant once envoys have registered.

Related

• SQLite actor startup picks the storage schema by probing the actor KV subspace for legacy v1 data. Existing v1 data stays on v1, and actors without v1 data start on v2.
• PostgreSQL: Configure the experimental PostgreSQL backend
• File System: Configure file system storage for development

Source doc path: /docs/self-hosting/configuration