Environment variables reference for Vulpy Commerce

A catalog of the environment variables that configure Vulpy Commerce: install, Fox, data directories, storefront, analytics, and build-time flags.

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.