Configuration

Config File

Default location:

Platform	Path
macOS / Linux	`~/.msgvault/config.toml`
Windows	`C:\Users\<you>\.msgvault\config.toml`

Override the data directory with the MSGVAULT_HOME environment variable or the --home flag (see below).

[data]
# Base data directory (default: ~/.msgvault)
data_dir = "/path/to/msgvault/data"

# Database URL (default: {data_dir}/msgvault.db)
database_url = "/path/to/msgvault.db"

[oauth]
# Path to Google OAuth client secrets JSON (required)
client_secrets = "/path/to/client_secret.json"

[sync]
# Gmail API rate limit (requests per second)
rate_limit_qps = 5

[server]
# API server settings (used by `msgvault serve`)
api_port = 8080
bind_addr = "127.0.0.1"
api_key = "your-secret-key"

[remote]
# Remote msgvault endpoint for CLI remote mode
url = "http://nas-ip:8080"
api_key = "remote-api-key"
allow_insecure = true

# Scheduled sync accounts
[[accounts]]
email = "you@gmail.com"
schedule = "0 * * * *"
enabled = true

Windows Paths

TOML treats backslashes inside double-quoted strings as escape characters. On Windows, this means native paths like "C:\Users\you\..." will cause a parse error.

Use one of these formats instead:

# Forward slashes (recommended)
client_secrets = "C:/Users/you/Downloads/client_secret.json"

# Single-quoted string (backslashes are literal)
client_secrets = 'C:\Users\you\Downloads\client_secret.json'

Sections

`[data]`

Key	Default	Description
`data_dir`	`~/.msgvault`	Base directory for all data
`database_url`	`{data_dir}/msgvault.db`	SQLite database path

Attachments and OAuth tokens are stored in subdirectories of data_dir (attachments/ and tokens/ respectively). These paths are not independently configurable.

`[oauth]`

Key	Default	Description
`client_secrets`	—	Path to Google OAuth `client_secret.json` (required)

`[sync]`

Key	Default	Description
`rate_limit_qps`	`5`	Gmail API requests per second

`[server]`

Settings for the web server started by msgvault serve. See Web Server for endpoint documentation.

Key	Default	Description
`api_port`	`8080`	Port the server listens on
`bind_addr`	`127.0.0.1`	Bind address
`api_key`	—	API key for authentication
`allow_insecure`	`false`	Allow non-loopback binding without `api_key`
`cors_origins`	`[]`	Allowed CORS origins
`cors_credentials`	`false`	Allow credentials in CORS requests
`cors_max_age`	`0`	CORS preflight cache duration in seconds

`[remote]`

When set, CLI commands read from the remote server by default for supported operations.

Key	Default	Description
`url`	—	Remote API base URL (e.g. `http://nas-ip:8080`)
`api_key`	—	API key used by remote commands
`allow_insecure`	`false`	Allow HTTP remote connections

Affected CLI commands: search, show-message, stats, list-accounts.

`[[accounts]]`

Scheduled sync accounts for the web server. Each [[accounts]] entry defines a cron schedule for automatic background syncing.

Key	Default	Description
`email`	(required)	Gmail account email address
`schedule`	—	Cron expression for sync schedule (e.g., `0 * * * *`)
`enabled`	`true`	Whether scheduled sync is active for this account

Overriding the Home Directory

By default, msgvault stores everything under ~/.msgvault (macOS/Linux) or C:\Users\<you>\.msgvault (Windows). To use a different location, you have two options:

--home flag (per-command):

msgvault sync --home /mnt/data/msgvault

MSGVAULT_HOME environment variable (persistent):

export MSGVAULT_HOME=/mnt/data/msgvault

Both options are equivalent: config.toml is loaded from the specified directory, and all data (database, tokens, attachments) is stored there. The --home flag takes priority over MSGVAULT_HOME.

Environment Variables

Variable	Description
`MSGVAULT_HOME`	Base directory for all data (default: `~/.msgvault`)
`MSGVAULT_REMOTE_URL`	Remote URL for `export-token` (flag > env > config)
`MSGVAULT_REMOTE_API_KEY`	Remote API key for `export-token` (flag > env > config)

File Locations

All data lives under the msgvault home directory (~/.msgvault on macOS/Linux, C:\Users\<you>\.msgvault on Windows). The directory is created automatically on first use.

File	Description
`config.toml`	Configuration file
`msgvault.db`	SQLite database (system of record)
`attachments/`	Content-addressed attachment files
`tokens/`	OAuth tokens per account
`analytics/`	Parquet cache files for TUI