Environment variables reference for Vulpy Commerce

Vulpy Commerce is configured through environment variables stored in .env at the project root for local development, and in environments/<name>/.env for each deployed environment. Some variables are evaluated at build time and baked into images, while others are read at runtime. This page catalogs the variables Vulpy Commerce recognizes. Medusa and Payload also read their own upstream variables. For the full upstream lists, see the Medusa configuration docs and the Payload configuration docs.

Ask Fox to set env vars in dev. These tables are the map; Fox knows which vars are bake-time and can add or change them in your .env for you.Try prompts like:

“Which env vars are bake-time?”
“Add NEXT_PUBLIC_GTM_ID=GTM-XXX to my dev env.”
“Diff my dev .env against .env.example.”

Install and lifecycle

Variable	Purpose	Notes
`VULPY_IMDS_LOCK`	Blocks EC2/Lightsail IMDS access from the host and containers.	Default is enabled. Set to `0` to opt out so Fox can use the VM IAM role for Bedrock. Check status with `pnpm vulpy hermes doctor`.
`COMPOSE_PROJECT_NAME`	Docker Compose project name used to isolate environments.	Changing this lets you run dev, staging, and live as separate Compose projects.
`SEED_ON_START`	Whether to seed sample data when Medusa starts.	Useful for fresh installs and CI.
`SYNC_PUBLISHABLE_KEY`	Whether to synchronize the Medusa publishable API key across environments.	Helps keep storefront keys consistent during deploys.

Data directories

Variable	Purpose	Notes
`POSTGRES_DATA_DIR`	Host path for Postgres data.	Defaults under `.data/postgres/`.
`REDIS_DATA_DIR`	Host path for Redis data.	Defaults under `.data/redis/`.
`MATOMO_DATA_DIR`	Host path for Matomo application data.	Defaults under `.data/matomo/`.
`MATOMO_DB_DATA_DIR`	Host path for the Matomo database.	Defaults under `.data/matomo-db/`.

Do not place data directories on NTFS or exFAT volumes when running on Linux. Postgres and Redis require POSIX file semantics, and NTFS/exFAT can cause permission and locking errors.

Storefront and CMS

Variable	Purpose	Notes
`PAYLOAD_SECRET`	Secret key used by Payload CMS for authentication and encryption.	Must be set before starting the CMS.
`CMS_STRICT`	Enables strict validation in Payload CMS.	Set to enforce stricter schema and field checks.
`NEXT_PUBLIC_GTM_ID`	Google Tag Manager container ID for the storefront.	Injected into the Next.js build.
`REQUIRE_LOGIN_FOR_PRICES`	Requires customer authentication before showing product prices.	Bake-time variable. Changing it requires rebuilding the storefront Docker image.

REQUIRE_LOGIN_FOR_PRICES is baked into the storefront image at build time. If you change this value, rebuild and redeploy the storefront container for the change to take effect.

Domains

These labels are used during install and can be overridden per environment.

Variable	Purpose	Default
`SHOP_DOMAIN`	Public domain for the storefront.	Set during install.
`PREVIEW_DOMAIN`	Domain for preview deployments.	Set during install.
`API_DOMAIN`	Domain for the Medusa API.	Set during install.
`MATOMO_DOMAIN`	Domain for the self-hosted Matomo instance.	`analytics.<domain>`

Fox and WebUI

Variable	Purpose	Notes
`VULPY_WEBUI_IFRAMES`	Controls whether the Fox WebUI allows iframe embedding.	Adjust based on your security requirements.

Next steps

Production deploy checklist

Review the steps to take an environment live, including domain and env var verification.

CLI reference

See the full list of pnpm vulpy commands for managing environments, Fox, and edge nodes.

Get Started

Fox and the WebUI

Running Your Shop

Analytics

Environments and Deployment

Customize

Reference

Environment variables reference for Vulpy Commerce

Install and lifecycle

Data directories

Storefront and CMS

Domains

Fox and WebUI

Next steps

Production deploy checklist

CLI reference

​Install and lifecycle

​Data directories

​Storefront and CMS

​Domains

​Fox and WebUI

​Next steps

Production deploy checklist

CLI reference

Install and lifecycle

Data directories

Storefront and CMS

Domains

Fox and WebUI

Next steps