# 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

- 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](/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_