Configuration
Grove is configured with environment variables, read once at startup from the
environment and an optional
.env file in the working directory. Invalid or inconsistent values
stop the server with a message that names the variable.
Durations use Go syntax such as 30s, 5m or 6h. Sizes are in bytes. Boolean flags are on when set to true.
Core
| Variable |
Default |
Description |
DATA_DIR |
– |
Required. Where Grove keeps repository mirrors (repos/), search indices (indices/), the SQLite database and the extension signing key. Persist it. |
SECRET_KEY |
– |
Required. Encrypts code host tokens at rest. Generate with openssl rand -base64 32. Changing it makes stored tokens unreadable; they then have to be entered again. The placeholder from example.env is rejected. |
PORT |
8080 |
HTTP port. |
DSN |
$DATA_DIR/db.sqlite |
Database. A file path selects SQLite; a postgres:// or postgresql:// URL selects PostgreSQL. |
PUBLIC_URL |
– |
The origin users reach Grove at, e.g. https://grove.example.com (no path). Required with OIDC; also used for MCP discovery and the self-updating browser extension. An https URL forces secure cookies. When unset, Grove uses the request’s Host header; it never trusts X-Forwarded-Host. |
| Variable |
Default |
Description |
CTAGS_PATH |
universal-ctags or ctags-universal on PATH |
Path to universal-ctags. Must exist if set. Without ctags, symbols aren’t indexed: no definitions and no sym:. |
GIT_COMMAND |
git on PATH |
Path to git. Must exist if set. Without git, blame, commit diffs and diff search are unavailable. |
Authentication
See Authentication for how the modes fit together.
| Variable |
Default |
Description |
OIDC_PROVIDER_URL |
– |
Issuer URL of your OIDC provider. |
OIDC_CLIENT_ID |
– |
OAuth client ID. Setting it enables OIDC sign-in and requires OIDC_PROVIDER_URL and PUBLIC_URL. |
OIDC_CLIENT_SECRET |
– |
OAuth client secret. |
AUTH_PROXY_HEADER_USER |
– |
Header carrying the user name from an authenticating reverse proxy, e.g. X-Auth-User. Set together with the email header. |
AUTH_PROXY_HEADER_EMAIL |
– |
Header carrying the user’s email, e.g. X-Auth-Email. |
PUBLIC_INSTANCE |
false |
Lets anyone search and read code without signing in. Settings still need an account. |
COOKIE_SECURE |
false |
Always set the Secure flag on session cookies, regardless of X-Forwarded-Proto. Turn on for any HTTPS deployment where TLS ends at a proxy. |
INSECURE_ALLOW_ALL |
false |
Turns off authentication entirely. Local development only. |
Network
| Variable |
Default |
Description |
CORS_ALLOWED_ORIGINS |
– |
Comma-separated browser origins allowed to call the API cross-origin. Unset sends no CORS headers. Avoid * on an authenticated instance. |
MCP_ALLOWED_ORIGINS |
– |
Comma-separated origins allowed to call /mcp from a browser, as a DNS-rebinding defense. MCP clients send no Origin and are unaffected. Unset allows any; set it on untrusted networks. |
MAX_REQUEST_BODY_BYTES |
1048576 |
Largest request body accepted by /graphql and the MCP endpoints. |
Syncing and indexing
| Variable |
Default |
Description |
RESYNC_INTERVAL |
30 |
Minutes between code host syncs. 0 turns syncing off, along with the other scheduled jobs. Between syncs, repositories are fetched on their own schedule based on how often they change. |
INDEX_MAX_FILE_BYTES |
2097152 (2 MiB) |
Largest file whose content is indexed; larger files are only found by name. Changing it reindexes every repository. |
ENABLE_REPO_DELETION |
false |
Deletes repositories (mirror, index and database rows) once they’ve disappeared from their code host. Without it they are only marked as deleted. |
ZOEKT_LANG_LOOKUP |
false |
Use the indexed language of a file for code navigation instead of guessing it from the extension. More accurate, slightly slower. |
DISABLE_FETCH |
false |
Don’t clone or fetch repositories. For development. |
DISABLE_CRON |
false |
Don’t run scheduled jobs (syncs, saved searches, deletions). For development. |
Search
| Variable |
Default |
Description |
SEARCH_MAX_RESULTS |
100 |
Files a search returns when neither the query (count:) nor the client asks for a number. |
SEARCH_RESULT_LIMIT |
5000 |
Most files any search returns, count:all included. At least SEARCH_MAX_RESULTS. |
SEARCH_MATCH_LIMIT |
20000 |
Most matched lines across all files of a search. |
SEARCH_TIMEOUT |
40s |
How long an interactive search (web app, API, MCP) may run before returning what it found so far, marked incomplete. API clients may ask for less, or for up to 60 seconds. Also bounds diff search. |
SAVED_SEARCH_TIMEOUT |
30s |
Time limit for a scheduled saved-search run (1s to 10m). Runs that exceed it are logged as errors and their results discarded. |
EXPORT_MAX_RESULTS |
10000 |
Most files, repositories or commits in a result download. |
EXPORT_MAX_MATCHES |
100000 |
Most matched lines in a result download. |
EXPORT_TIMEOUT |
60s |
Search time for a result download. Downloads cut short say so in their last line. |
Limits
| Variable |
Default |
Description |
MAX_DISPLAY_BYTES |
10485760 (10 MiB) |
Largest file, commit diff or blame Grove loads to display. Larger files are offered as a raw download. |
Email
Email powers saved-search alerts. It is off unless both SMTP_HOST and SMTP_FROM are set.
| Variable |
Default |
Description |
SMTP_HOST |
– |
SMTP server. |
SMTP_PORT |
25 |
SMTP port. |
SMTP_FROM |
– |
Sender address. |
SMTP_USER |
– |
User name; set together with SMTP_PASS. |
SMTP_PASS |
– |
Password. |
Logging and metrics
| Variable |
Default |
Description |
LOG_FORMAT |
text |
text or json. |
LOG_LEVEL |
INFO |
DEBUG, INFO, WARN or ERROR. |
METRICS_PORT |
– |
Serve Prometheus metrics on this port instead of at /metrics on the main port. Use it to keep metrics off the public listener. |
DISK_USAGE_INTERVAL |
6h |
How often the data directory’s size is recomputed for Settings → Stats (between 1h and 24h). |
Example
# .env
DATA_DIR=/data
SECRET_KEY=paste-the-output-of-openssl-rand-base64-32
PUBLIC_URL=https://grove.example.com
COOKIE_SECURE=true
MCP_ALLOWED_ORIGINS=https://grove.example.com
OIDC_PROVIDER_URL=https://accounts.google.com
OIDC_CLIENT_ID=123456789-abc.apps.googleusercontent.com
OIDC_CLIENT_SECRET=GOCSPX-…
DSN=postgres://grove:secret@db:5432/grove?sslmode=disable
SMTP_HOST=smtp.example.com
SMTP_FROM=grove@example.com
LOG_FORMAT=json
METRICS_PORT=9090