Environment variables

Core

Variable	Default	Meaning
PORT	8080	Listen port.
JWT_SECRET	dev-secret-do-not-use-in-production	Token signing secret. A value not starting with dev-secret puts the server into “production posture”.
GROVEBACK_PROJECT_ID	proj_dev	The single project id to mount.
GROVEBACK_MULTI_PROJECT	off	1/true serves every active control-plane project from one instance, routed by the token’s pid.
MONGO_URL	—	Use MongoDB instead of in-memory storage. Must be a replica set for realtime.
REDIS_URL	—	BullMQ queue for background triggers and cron. Unset means functions run inline with no persistent queue.
APP_URL	http://localhost:<PORT>/dashboard	Where Stripe checkout and portal return the browser.
GROVEBACK_BASE_URL	—	This server’s public URL; OAuth redirect_uris point here.
GROVEBACK_SECRET_KEY	—	Master key encrypting integration and BYO secrets at rest. Required in production.
GROVEBACK_POLICIES_FILE	groveback.policies.json	File-based default collection policies.
GROVEBACK_OPERATORS	empty	Comma-separated emails allowed to use /api/v1/control/admin/*. Unset means those routes fail closed.
GROVEBACK_CLOUD	false	true makes BYO Mongo enforce the SSRF guard and require TLS. The default suits self-hosting, where localhost clusters are normal.
GROVEBACK_BYO_MAX_CLIENTS	50	LRU cap on cached per-project BYO Mongo clients.

Local development

Variable	Default	Meaning
GROVEBACK_DEV_ADMIN_KEY	—	Install a known admin key at boot. Refused in a production posture unless GROVEBACK_DEV=1.
GROVEBACK_DEV	—	1 asserts “this really is a dev server”, so an inherited JWT_SECRET does not block the dev key. Set by grove dev.
GROVEBACK_LOCAL_STATUS	—	Path to the snapshot the dashboard’s Local section reads. Set by grove dev.

Storage

Variable	Default	Meaning
S3_ENDPOINT	—	Enables the S3 blob backend. All three of endpoint, key and secret must be set, or S3 is off.
S3_ACCESS_KEY_ID	—
S3_SECRET_ACCESS_KEY	—
S3_BUCKET	groveback
S3_REGION	—
GROVEBACK_MAX_FILE_SIZE	10485760 (10 MB)	Per-file upload cap in bytes. Mongo-backed blobs additionally cap at the 16 MB BSON limit.

Functions

Variable	Default	Meaning
GROVEBACK_FUNCTION_TIMEOUT_MS	10000	Per-run execution timeout.
GROVEBACK_FUNCTION_PRE_TIMEOUT_MS	2000	Per-hook timeout for pre-write hooks.
GROVEBACK_FUNCTION_PRE_CHAIN_BUDGET_MS	5000	Cap on a whole pre-hook chain.
GROVEBACK_FUNCTION_POOL_SIZE	internal	Worker pool size.
GROVEBACK_FUNCTION_MAX_WAITERS	poolSize * 8	Queue depth cap; beyond it runs are rejected immediately (HTTP 503).
GROVEBACK_FUNCTION_QUEUE_TIMEOUT_MS	5000	Budget for waiting on a free worker — separate from the run timeout, so waiting never eats a function’s own time.

Note

The function worker strips its own environment at startup, preserving only PATH. None of these leak into handler code.

Embeddings and vector search

Variable	Default	Meaning
EMBEDDINGS_URL	—	A local TEI or OpenAI-compatible endpoint.
EMBEDDINGS_DIM	384	Local model dimensions.
EMBEDDINGS_MODEL	text-embeddings-inference	Local model name.
EMBEDDINGS_PROVIDER	local when EMBEDDINGS_URL is set, else mock	Default provider.
OPENAI_API_KEY	—	Opt into the OpenAI provider.
VOYAGE_API_KEY	—	Opt into the Voyage provider.

Email

Variable	Default	Meaning
RESEND_API_KEY	—	Enables transactional email. Without it, the email-verification gate is disabled rather than locking users out.
RESEND_FROM	—	From address.
RESEND_API_URL	Resend’s default	Override the API base URL.

Billing

Variable	Default	Meaning
STRIPE_SECRET_KEY	—	Unset means billing is disabled and nothing is limited — the self-host default.
GROVEBACK_BILLING	enabled	0/false forces billing off even with a Stripe key.
STRIPE_PRICE_PRO · STRIPE_PRICE_SCALE	—	Recurring price ids per plan.
STRIPE_WEBHOOK_SECRET	—	Without it every delivery to /api/v1/billing/webhook is rejected and upgrades never apply.
STRIPE_API_URL	https://api.stripe.com	For a Stripe-compatible backend.
STRIPE_WEBHOOK_DEBUG	—	1/true dumps every delivery’s headers and raw body. Troubleshooting only — that body is unauthenticated input.

Build metadata

Variable	Default	Meaning
GROVEBACK_COMMIT	null	Commit sha reported at /api/v1/health.
CHART_VERSION	null	Helm chart version, same endpoint.

Client-side

Not read by the backend.

Variable	Read by	Meaning
GROVE_ADMIN_KEY	the CLI	The admin key for gen, pull, push, seed, status.
GROVE_URL	the generated client	Overrides the baked URL at runtime, so one committed client serves local and production.
GROVEBACK_URL · GROVEBACK_API_KEY · GROVEBACK_MCP_READONLY	the MCP server	See the MCP reference.

Production posture

A JWT_SECRET that does not start with dev-secret puts the server into production posture, which changes two behaviors:

• GROVEBACK_DEV_ADMIN_KEY is refused unless GROVEBACK_DEV=1. A known admin key on a production deployment is not a warning-level mistake.
• GROVEBACK_SECRET_KEY becomes required — without it, stored secrets cannot be decrypted.

Stale entries

If you are working from an old .env.example, these are no longer read anywhere: OAUTH_GOOGLE_CLIENT_ID, OAUTH_GOOGLE_CLIENT_SECRET, OAUTH_GITHUB_CLIENT_ID, OAUTH_GITHUB_CLIENT_SECRET, GROVEBACK_OAUTH_REDIRECTS. OAuth is configured per project now.

MINIO_ROOT_USER and MINIO_ROOT_PASSWORD are consumed by Docker Compose, not the server.