Every environment variable a self-hosted Mogplex reads, grouped by feature, with required, build-time, and default values marked.
.env.example in the repository is the starting template. Copy it to
.env.local for local development, or to .env for Docker.
NEXT_PUBLIC_* values are build-time
Next.js compiles every NEXT_PUBLIC_* value into the client bundle when it
builds. Changing one at runtime has no effect. Rebuild after each change. With
Docker, pass them as --build-arg.
Trigger.dev tasks need the same server variables as the app. See
Background jobs .
Variable Notes MOGPLEX_DATA_BACKENDneon.NEXT_PUBLIC_MOGPLEX_DATA_BACKENDneon. Must match MOGPLEX_DATA_BACKEND. Build-time.APP_URL or NEXT_PUBLIC_APP_URLPublic URL of the deployment, such as https://mogplex.example.com. APP_URL wins and is read at runtime, so one image serves any domain. DATABASE_URLOwner connection. Migrations use it, and the app falls back to it. DATABASE_URL_UNPOOLEDDirect connection, for pg LISTEN. BETTER_AUTH_SECRETopenssl rand -base64 32.CRON_SECRETBearer token for /api/cron/* and machine-only routes. INTERNAL_API_SECRETServer-to-server sandbox actions. CONNECTIONS_ENCRYPTION_KEY32-byte hex key (openssl rand -hex 32) that encrypts saved connection credentials. Do not rotate without a plan: see Operations . EMAIL_UNSUBSCRIBE_SECRETSigns unsubscribe links. The app throws in production without it. One sign-in provider AUTH_GITHUB_*, AUTH_GOOGLE_*, AUTH_MICROSOFT_*, or Resend for email and password.
pnpm setup:doctor checks these and the optional services below.
Variable Notes MOGPLEX_RUNTIME_DATABASE_URLPreferred app connection, as the least-privilege service_role. MOGPLEX_RUNTIME_DATABASE_URL_UNPOOLEDDirect URL for service_role.
See Database and auth .
Variable Notes BETTER_AUTH_URLDefaults to NEXT_PUBLIC_APP_URL. BETTER_AUTH_API_KEYOptional. Connects the better-auth.com dashboard. AUTH_GITHUB_CLIENT_ID, AUTH_GITHUB_CLIENT_SECRETGitHub sign-in. Callback: /api/auth/callback/github. AUTH_GOOGLE_CLIENT_ID, AUTH_GOOGLE_CLIENT_SECRETGoogle sign-in. Callback: /api/auth/callback/google. AUTH_MICROSOFT_CLIENT_ID, AUTH_MICROSOFT_CLIENT_SECRETMicrosoft sign-in. Callback: /api/auth/callback/microsoft. AUTH_MICROSOFT_TENANT_IDDefault common (any Microsoft account). RESEND_API_KEYRequired for email and password sign-up (verification email). WAITLIST_FROM_EMAILDefault sender, on a domain verified in Resend. AUTH_FROM_EMAIL, BILLING_FROM_EMAILOptional senders. Fall back to WAITLIST_FROM_EMAIL.
Variable Notes GITHUB_APP_IDGitHub App ID. GITHUB_APP_NAMEGitHub App slug, as in github.com/apps/<slug>. GITHUB_APP_PRIVATE_KEYPEM. Write newlines as \n in single-line env files. GITHUB_WEBHOOK_SECRETMust match the App's webhook secret. GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRETClassic GitHub OAuth app for repository listing and reauthorization. The GitHub App's own client credentials do not work here. MOGPLEX_SETUP_ENABLED1 enables /admin/setup/github in production while the GitHub App is unconfigured. Remove it after setup.
See GitHub App .
Variable Notes TRIGGER_PROJECT_REFYour Trigger.dev project ref. pnpm trigger:* refuses to run without it. TRIGGER_SECRET_KEYSecret key for the Trigger.dev environment. TRIGGER_API_URLOnly for a self-hosted Trigger.dev instance. The SDK and pnpm trigger:* both use it. TRIGGER_CLI_ENV_FILESOptional. Extra comma-separated env files for pnpm trigger:deploy.
Variable Notes PLATFORM_VERCEL_TOKENVercel token that creates sandboxes. PLATFORM_VERCEL_TEAM_IDVercel team that owns the sandboxes. VERCEL_PROJECT_ID or PLATFORM_VERCEL_PROJECT_IDVercel project for the sandboxes. PLATFORM_SANDBOX_COST_CENTS_PER_SECONDOptional. Cost-reporting rate. Default 0.0028.
Variable Notes AI_GATEWAY_API_KEYPlatform model access through Vercel AI Gateway. OPENROUTER_API_KEYOptional. Model catalog sync. OPENAI_API_KEYOptional. Memory embeddings. Without it, memory search uses plain text matching. EXA_API_KEYOptional. Agent web search and page extraction. Server-side only. EXA_RESEARCH_SECRETOptional. Lets Trigger.dev workers use web search through the app. AUTOMATION_GATEWAY_CACHINGOptional. off turns off prompt caching for automation jobs. AUTOMATION_GATEWAY_FALLBACK_MODELSOptional. Comma-separated fallback models for automation jobs. DECISION_MODES, DECISIONS_DISABLEDOptional. Overrides for the decision layer. MOGPLEX_HARNESS_ACPOptional. off runs Codex through its CLI instead of the Agent Client Protocol. MOGPLEX_OPENAI_COMPATIBLE_BASE_URLOptional. Your OpenAI-compatible endpoint, such as LiteLLM, vLLM, or Ollama. MOGPLEX_OPENAI_COMPATIBLE_API_KEYOptional. Sent only to that endpoint. MOGPLEX_OPENAI_COMPATIBLE_MODELSComma-separated model IDs, with an optional id=Label.
Variable Notes MOGPLEX_SELF_HOSTED1 grants platform AI and sandbox access to every signed-in user and hides billing. Ignored while STRIPE_SECRET_KEY is set.MOGPLEX_SELF_HOSTED_ALLOWED_EMAIL_DOMAINSOptional. Limits self-host mode to these email domains. PLATFORM_ACCESS_EMAILSComma-separated emails with platform AI and sandbox access. PLATFORM_ACCESS_EMAIL_DOMAINSComma-separated domains, such as example.com. PLATFORM_ACCESS_USER_IDSComma-separated Mogplex user IDs.
See Give users access .
Variable Notes SLACK_CLIENT_ID, SLACK_CLIENT_SECRETSlack app OAuth credentials. SLACK_SIGNING_SECRETVerifies requests to /api/webhooks/slack. SLACK_REDIRECT_URIOptional. Default ${NEXT_PUBLIC_APP_URL}/api/integrations/slack/callback.
Variable Notes MOGPLEX_API_URLOptional. Overrides the host for the app's calls to its own API. MOGPLEX_MCP_RESOURCE_URLOptional. OAuth protected-resource URL. Default ${NEXT_PUBLIC_APP_URL}/api/v1/mogplex/mcp. MOGPLEX_MCP_ALLOWED_ORIGINSOptional. Comma-separated browser origins that may call the MCP endpoint. Server-side MCP clients do not need it.
Variable Notes NEXT_PUBLIC_SENTRY_DSNBrowser DSN. Build-time. SENTRY_DSNServer DSN. Defaults to NEXT_PUBLIC_SENTRY_DSN. SENTRY_ORG, SENTRY_PROJECT, SENTRY_AUTH_TOKENSource map upload during builds. SENTRY_ENVIRONMENT, SENTRY_TRACES_SAMPLE_RATEOptional overrides. NEXT_PUBLIC_SENTRY_TRACES_SAMPLE_RATE, NEXT_PUBLIC_SENTRY_REPLAYS_SESSION_SAMPLE_RATE, NEXT_PUBLIC_SENTRY_REPLAYS_ON_ERROR_SAMPLE_RATEOptional browser sampling. Build-time.
Leave these unset to run without billing. Then grant access with the
allowlists .
Variable Notes STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRETYour Stripe account. Webhook: /api/webhooks/stripe. CAPACITY_BILLING_OPERATIONS_ENABLEDDefault false. Turns on capacity billing operations. CAPACITY_BILLING_LIVE_WRITES_ENABLEDDefault false. Required with a live Stripe key. CAPACITY_BILLING_PILOT_ACCOUNT_IDSComma-separated billing account IDs for the reserved-concurrency pilot.
Variable Notes COMPOSE_PROFILESpostgres starts the bundled Postgres; .env.example sets it. Remove it when DATABASE_URL points at an external database.MOGPLEX_VERSIONImage tag to run, such as v0.2.0. Default latest. MOGPLEX_IMAGEImage repository. Default ghcr.io/mogplex/mogplex; set it to use a mirror. MOGPLEX_PORTHost port for the app. Default 3000. POSTGRES_PASSWORDPassword for the bundled Postgres. Ignored when you set DATABASE_URL. CRON_TARGET_URLBase URL the cron scheduler calls. Compose sets it to the app service.
Variable Notes NEXT_PUBLIC_C15T_URLOptional. Hosted cookie-consent backend. If unset, consent is stored only in the browser. Build-time. NEXT_PUBLIC_VERCEL_APP_CLIENT_ID, VERCEL_APP_CLIENT_SECRETOptional. Sign in with Vercel (identity only). Callback: /api/auth/vercel/callback. Build-time client ID. NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEYLegacy Supabase deployments only. Leave them empty for Neon.