# 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](/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:

```bash
# 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:

```json
{
	"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

- RivetKit actor runtime persistence lives in SQLite. Existing actor KV data is imported into SQLite the first time an actor wakes on the migrated runtime, then the original KV data is left frozen for downgrade safety.
- [PostgreSQL](/docs/self-hosting/postgres): Configure the experimental PostgreSQL backend
- [File System](/docs/self-hosting/filesystem): Configure file system storage for development

_Source doc path: /docs/self-hosting/configuration_