Configuration

mddb reads config.toml once at startup. Restart the service after you edit it. A malformed file or an unknown key stops startup and names the offending key.

Two files hold instance settings

Both files live in the config directory: ~/.config/mddb/, or $XDG_CONFIG_HOME/mddb/ when that variable is set. Start mddb with -config-dir DIR to use another directory. mddb -help lists the flags.

File	Owner	Contents
config.toml	You	Listener, data directory, base URL, OAuth clients, GitHub App, voice, log level
settings.json	mddb	SMTP, quotas, and rate limits from the server settings page; the session signing secret and Web Push keys

mddb creates settings.json with mode 0600 on first start. Change its values at /settings/server as the server administrator, not by hand.

The example config.toml lists every key, commented out with its default value. Uncomment a line to override it. The installer and the setup wizard create config.toml for you. To copy the example from a release archive or a clone:

mkdir -p ~/.config/mddb
install -m 600 config.toml ~/.config/mddb/config.toml

config.toml holds OAuth client secrets and the GitHub App webhook secret. Keep it readable only by the server account.

Relative paths use two bases

• server.data_dir resolves against the working directory. The installed service runs in ~/mddb, so the default puts content in ~/mddb/data.
• server.geo_db, github.app.private_key_file, and voice-gateway.signing_private_key_pem resolve against the config directory.

Every path accepts ~ for your home directory and absolute paths.

Top-level keys

Key	Default	Effect
auto_update	"50 4 * * *"	Five-field cron schedule for stable-release updates, with up to five minutes of random delay. "" turns updates off.

Server keys

The [server] section:

Key	Default	Effect
http	"localhost:8080"	Listen address. :8080 also means localhost:8080. Use 0.0.0.0:8080 for all interfaces.
data_dir	"data"	Directory for workspace repositories and the db directory.
base_url	"http://localhost"	Public origin for OAuth callbacks, email links, and voice tokens. A localhost URL without a port takes the port from http.
geo_db	""	MaxMind MMDB file for IP geolocation. Empty skips country lookup.
allow_origins	[]	Allowed client origins. Empty turns filtering off.
trusted_proxies	[]	Address prefixes of reverse proxies that may set the client IP.

Set base_url to the address that users type, such as https://mddb.example.com. OAuth providers, the GitHub App, and an external voice gateway depend on it.

Restrict client origins

allow_origins accepts country codes, CIDR ranges, and the names local, tailscale, anthropic, github, and openai. Country codes require geo_db. When the list is not empty, mddb denies every other origin. mddb caches the GitHub and OpenAI address ranges for 24 hours in your user cache directory.

[server]
geo_db = "GeoLite2-Country.mmdb"
allow_origins = ["CA", "US", "local", "tailscale"]

To get a country database, create a free MaxMind GeoLite account and download GeoLite Country. MaxMind explains how to keep it current.

Trust only your own proxy

The client IP keys per-IP rate limits, sessions, and logs. mddb accepts X-Forwarded-For and X-Real-IP only from addresses in trusted_proxies. Leave it empty when clients connect directly. Behind a reverse proxy on the same host, set:

[server]
trusted_proxies = ["127.0.0.1/32", "::1/128"]

Without it, every client shares the proxy's address. See Serving over HTTPS.

Feature sections

Section	Guide
[oauth.google]	Authentication
[oauth.microsoft]	Authentication
[oauth.github]	Authentication
[github.app]	Git and GitHub sync
[voice-gateway]	Voice

The [debug] section has one key, log_level. It accepts debug, info, warn, or error, and defaults to info.