Environment Variables

Every variable across the Venelx components, grouped by where it's set. Annotated, commit-safe templates live in the monorepo under env/*.env.example — regenerate local .env files from them with ./scripts/bootstrap-env.sh all.

Key split rules

The most common misconfiguration is putting a variable on the wrong process. The rules:

Variable	API (`venelx-backend`)	Worker (`venelx-worker`)
`VENELX_DEPLOY_ROLE`	`api`	`worker`
`RUN_QUEUE_WORKER`	`false`	`true`
`WORKER_AGENT_ONLY`	unset	`true`
`B2_*`	all set	omit — use `B2_UPLOAD_VIA_API=true`
`EXPO_TOKEN`, `OUTPUT_DIR`, `PROJECT_DIR`	omit	set
`WORKER_AGENT_TOKEN`	set (ops fleet)	same value as API or `WORKER_PAIRING_TOKEN` (customer workers)
`CORS_ORIGINS`	set	omit
`NEXT_PUBLIC_*`	—	frontend / Vercel only

Frontend (Vercel — `venelx-frontend`)

Template: env/vercel.env.example. Redeploy after changing any NEXT_PUBLIC_* value.

Variable	Example	Purpose
`NEXT_PUBLIC_API_URL`	`https://api.venelx.com`	Base URL the browser calls for the REST API
`NEXT_PUBLIC_WS_URL`	`wss://api.venelx.com`	WebSocket base URL (live logs, worker updates)
`NEXT_PUBLIC_PRODUCT_NAME`	`Venelx`	Product name shown in the UI

The API must allow these origins back: set CORS_ORIGINS on venelx-backend to include your production and preview dashboard URLs.

API (`venelx-backend`)

Template: env/api.env.example (cloud) / env/backend-selfhost-mac.env.example (Mac + tunnel).

Process role & networking

Variable	Default / example	Purpose
`NODE_ENV`	`production`	Node environment
`VENELX_DEPLOY_ROLE`	`api`	Startup guard — must be `api` on the control plane
`PORT`	`4000`	HTTP listen port
`LISTEN_HOST`	`0.0.0.0` (cloud) / `127.0.0.1` (Mac + tunnel)	Bind address; only the tunnel should reach the port on a Mac
`RUN_QUEUE_WORKER`	`false`	Must stay `false` in production — no queue consumer on the API
`WORKER_AGENT_ONLY`	unset	Never set on the API (worker-only mode)
`WORKER_STRICT`	`true`	Route jobs only to workers advertising the platform
`CORS_ORIGINS`	`https://app.venelx.com,https://*.vercel.app`	Allowed browser origins
`PUBLIC_DOMAIN`	`api.venelx.com`	Public hostname of the API
`PUBLIC_API_URL`	`https://api.venelx.com`	External base URL — webhooks + GitHub callback must reach this
`PUBLIC_APP_URL`	`https://app.venelx.com`	Web dashboard URL for invites, auth links, email CTAs

Auth

Variable	Purpose
`API_SECRET`	Legacy/API-level secret
`AUTH_USERNAME` / `AUTH_PASSWORD`	Bootstrap admin credentials
`AUTH_JWT_SECRET`	Signs session JWTs
`AUTH_TOKEN_TTL_HOURS`	Session token lifetime (default `12`)
`REFRESH_TOKEN_SECRET`	Signs refresh tokens
`REQUIRE_EMAIL_VERIFICATION` / `SKIP_EMAIL_VERIFICATION`	Email-verification flow toggles

Database & queue

Variable	Purpose
`MONGODB_URI`	MongoDB Atlas connection string (Prisma)
`MONGODB_DB_NAME`	Database name (default `expo_forge`)
`DATABASE_URL`	Same Mongo URI, for Prisma tooling
`REDIS_URL`	BullMQ queue — Upstash `rediss://...` in split prod, `redis://127.0.0.1:6379` on a Mac
`BUILD_QUEUE_CONCURRENCY`	Jobs dequeued in parallel (default `2`)
`DISABLE_REDIS`	Set `true` only for customer-worker-only fleets without BullMQ

Worker fleet

Variable	Purpose
`WORKER_AGENT_TOKEN`	Shared secret for ops workers + internal routes (generate: `openssl rand -hex 24`)
`WORKER_HEARTBEAT_STALE_MS`	Mark a worker offline after this much silence (default `120000`)
`WORKER_HEARTBEAT_WRITE_MIN_MS`	Min gap between heartbeat DB writes (default `45000`)
`WORKER_INSTALLER_VERSION` / `WORKER_INSTALLER_BASE_URL`	Version + download base served for worker installers
`BACKEND_INSTALLER_VERSION` / `BACKEND_INSTALLER_BASE_URL`	Same, for the self-host backend installer

Product & encryption

Variable	Purpose
`PRODUCT_NAME`	Product name (`Venelx`)
`FORGE_MASTER_SECRET`	Master secret encrypting signing material / vault
`SIGNING_VAULT_MODE`	Vault mode (`ephemeral`)

GitHub / GitLab

See the GitHub guide for the full GITHUB_* table (OAuth client, callback URL, app slug, token sweep interval, PAT fallbacks). GitLab equivalents: GITLAB_CLIENT_ID, GITLAB_CLIENT_SECRET, GITLAB_HOST (optional).

AI, email, webhooks (optional)

Variable	Purpose
`GEMINI_API_KEY` / `OPENAI_API_KEY`	AI-assisted features
`SMTP_HOST` / `SMTP_PORT` / `SMTP_USER` / `SMTP_PASS` / `SMTP_FROM` / `SMTP_TO`	Outgoing email (Zoho SMTP in templates)
`SLACK_WEBHOOK_URL` / `OUTBOUND_WEBHOOK_URLS`	Alert webhooks
`PR_PREVIEW_PLATFORMS`	Platforms auto-built on PRs (default `android-preview`)

Artifacts (Backblaze B2) — API only

Variable	Purpose
`B2_KEY_ID` / `B2_APP_KEY`	B2 credentials
`B2_BUCKET_NAME`	Artifact bucket
`B2_ENDPOINT` / `B2_REGION`	S3-compatible endpoint + region
`B2_CDN_BASE_URL`	Optional CDN base for downloads
`B2_DELETE_LOCAL_AFTER_UPLOAD`	Free API disk after upload
`ARTIFACT_KEEP_COUNT`	Artifacts retained per project/platform (default `5`)
`ARTIFACT_PURGE_INTERVAL_HOURS`	Retention sweep interval (default `24`)

Billing (Lemon Squeezy)

Variable	Purpose
`LEMONSQUEEZY_WEBHOOK_SECRET`	Webhook HMAC verification (shared by all plans)
`LEMONSQUEEZY_STORE_ID` / `LEMONSQUEEZY_STORE_SLUG`	Store identifiers
`LEMONSQUEEZY_VARIANT_ID_PRO`	Pro plan variant
`LEMONSQUEEZY_VARIANT_ID_WORKER_ANNUAL`	Self-hosted worker annual plan (includes 2 slots)
`LEMONSQUEEZY_VARIANT_ID_WORKER_SLOT_ADDON`	Extra worker slot add-on
`LEMONSQUEEZY_API_KEY` / `LEMONSQUEEZY_TEST_MODE`	API access / test mode

Misc

Variable	Purpose
`FIREBASE_SERVICE_ACCOUNT_PATH`	FCM service-account JSON path (push notifications)
`VENELX_FASTLANE_DIR`	fastlane runtime for store submit (install once via `scripts/install-fastlane-runtime.sh`)
`TAILSCALE_IP`	Optional Tailscale CORS allowlist
`OUTPUT_DIR` / `OTA_BUNDLE_DIR`	Local paths (Mac self-host; default `~/.venelx/...`)

Worker (`venelx-worker`)

Templates: env/worker-mac.env.example (macOS, iOS ± Android) / env/worker-linux.env.example (Linux/WSL2, Android).

Variable	Default / example	Purpose
`VENELX_DEPLOY_ROLE`	`worker`	Startup guard
`WORKER_AGENT_ONLY`	`true`	Worker-only mode — no user-facing HTTP
`RUN_QUEUE_WORKER`	`true`	Consume BullMQ jobs
`WORKER_STRICT`	`true`	Consume only this worker's named queue (recommended for fleets)
`WORKER_NAME`	`mac-ios-1`	Unique per machine
`WORKER_PLATFORMS`	`ios` / `android-preview,android-production`	Platforms this worker accepts — drives scheduler routing
`API_URL`	`https://api.venelx.com`	Control plane base URL
`MAIN_HOST`	`127.0.0.1`	Legacy host hint when API shares the Mac
`REDIS_URL`	same as API	BullMQ queue (must match the API exactly)
`MONGODB_URI` / `DATABASE_URL` / `MONGODB_DB_NAME`	same as API	Job status updates via Prisma
`WORKER_AGENT_TOKEN`	same as API	Ops-fleet auth — customer workers use `WORKER_PAIRING_TOKEN` instead
`WORKER_PAIRING_TOKEN`	from dashboard	One-time pairing token for customer self-hosted workers
`VENELX_WORKER_CONFIG`	`~/.venelx/worker.env`	Config file path for installed customer workers
`FORGE_MASTER_SECRET`	same as API	Decrypts signing material at build time
`B2_UPLOAD_VIA_API`	`true`	Upload artifacts via API presign — no B2 keys on workers
`OUTPUT_DIR`	`~/.venelx/builds`	Build workspace (clones, logs, local artifacts)
`PROJECT_DIR` / `REPO_ROOT`	host paths	Optional fixed checkouts
`EXPO_TOKEN`	—	Expo/EAS access for npm + EAS-managed steps
`SKIP_PREBUILD`	`false`	Skip Expo prebuild step
`BUILD_TIMEOUT_MINUTES`	`60`	Per-build timeout
`ANDROID_HOME`	`/opt/android-sdk`	Android SDK location (Android workers)
`ANDROID_SERVICE_ACCOUNT_KEY`	path to JSON	Play service account for submit
`ANDROID_PACKAGE_NAME`	`com.example.app`	Default package name for submit
`WORKER_HEARTBEAT_INTERVAL_MS`	`45000`	Heartbeat cadence
`WORKER_CLAIM_POLL_MS`	`15000`	Job-claim poll interval (WS/HTTP)
`WORKER_WS_HTTP_FALLBACK_MS`	`30000`	Drop to HTTP when the WebSocket is down this long
`USE_TART_FOR_IOS` / `TART_VM_NAME`	optional	Run iOS builds inside a Tart VM

GitHub OAuth client fields (GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, GITHUB_OAUTH_MODE) may also be set on local workers that run OAuth-dependent steps.

MCP server (`@venelx/mcp`)

Variable	Required	Default	Purpose
`VENELX_TOKEN`	yes	—	Personal API token (`vx_...`) — see API tokens
`VENELX_API_URL`	no	`https://api.venelx.com`	API base URL (point at your self-hosted API)

Mobile app (`venelx-app`)

Template: env/app.env.example.

Variable	Purpose
`EXPO_PUBLIC_API_URL`	API base URL baked into the Expo app

Validating

bash

./scripts/validate-deploy-env.sh api venelx-backend/.env
./scripts/validate-deploy-env.sh worker venelx-worker/.env

← Reference API Overview →