--- title: "Environment Variables" description: "Reference for Agent-Native framework, workspace, authentication, and deployment environment variables." search: "environment variables env .env DATABASE_URL APP_URL BETTER_AUTH_SECRET Google OAuth workspace app" --- # Environment Variables This page covers the environment variables owned by the Agent-Native framework and workspace runtime. It is not a setup inventory of every template or deployment system in this repository. Template-only values stay in the maintainer inventory; the setup tables below focus on the shared configuration most apps need. For a normal app, start with the [Agent-Native app configuration guide](/docs/agent-native-config), then use [Deployment: Environment Variables](/docs/deployment-environment-variables) and [Authentication](/docs/authentication) for the deliberate environment-only parts. LLM provider keys can be app-wide fallbacks on self-hosted deployments; production Hosted-workspace runtimes block that fallback. See [LLM provider keys](#llm-provider-keys) for local setup, scoped keys, and deployment sharing and billing. Keep user-, organization-, and workspace-scoped credentials in the database-backed secret or connection store. For committed, non-secret app defaults, use `agent-native.config.ts` first. If a public config value must vary by deployment, use its deterministic `AGENT_NATIVE_CONFIG_` alias. That alias is the final override of the typed/JSON config and also becomes part of the public browser bundle. Do not create another standalone Vite-prefixed or Agent-Native-prefixed variable for a public setting already represented by the config guide. ## Start with Agent-Native app configuration The typed config is the primary documentation and default source for public app behavior. Its deployment aliases are the standard environment override: | Config path | Deployment override alias | | ------------------------------ | -------------------------------------------------- | | `onboarding.firstRun` | `AGENT_NATIVE_CONFIG_ONBOARDING_FIRST_RUN` | | `runtime.auth.enabled` | `AGENT_NATIVE_CONFIG_RUNTIME_AUTH_ENABLED` | | `runtime.database.required` | `AGENT_NATIVE_CONFIG_RUNTIME_DATABASE_REQUIRED` | | `runtime.environment.required` | `AGENT_NATIVE_CONFIG_RUNTIME_ENVIRONMENT_REQUIRED` | | `deployment.environment` | `AGENT_NATIVE_CONFIG_DEPLOYMENT_ENVIRONMENT` | | `diagnostics.failOnBuild` | `AGENT_NATIVE_CONFIG_DIAGNOSTICS_FAIL_ON_BUILD` | | `instructions.runtime` | `AGENT_NATIVE_CONFIG_INSTRUCTIONS_RUNTIME` | | `instructions.development` | `AGENT_NATIVE_CONFIG_INSTRUCTIONS_DEVELOPMENT` | | `translations.locales` | `AGENT_NATIVE_CONFIG_TRANSLATIONS_LOCALES` | | `changelog.enabled` | `AGENT_NATIVE_CONFIG_CHANGELOG_ENABLED` | | `harness` | `AGENT_NATIVE_CONFIG_HARNESS` | | `harness.runtimes` | `AGENT_NATIVE_CONFIG_HARNESS_RUNTIMES` | Use [Agent-Native app configuration](/docs/agent-native-config) for the full schema, mode-aware examples, JSON fragments, and precedence rules. The resolved public config is bundled into the browser, so it must contain only non-secret app policy. Some non-secret environment variables remain deliberate exceptions because they configure server-only behavior, platform facts, routing, or deployment secrets. Server-only product controls use the framework's `defineAppConfig()` schema and its declared aliases; they are not public `agent-native.config.ts` fields. The maintainer inventory's generated **Declared app configuration** section is the exhaustive list of those server fields and aliases. ## Server, environment-only, and deployment variables The table below covers values that belong to the running deployment, a server-only config surface, or an environment-only compatibility surface. For public app behavior, use the config paths above instead. | Variable | What it controls | Supported values or format | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | | `DATABASE_URL` | Primary PostgreSQL connection. Local development falls back to PGlite when it is unset. Production also accepts `_DATABASE_URL` or Netlify's `NETLIFY_DATABASE_URL`. | A PostgreSQL URL, or unset for local PGlite. | | `APP_URL` | Optional canonical public origin used for auth, OAuth, A2A, webhooks, and generated links. Netlify and Vercel metadata are inferred when it is unset. | An absolute public `http(s)` origin. | | `BETTER_AUTH_URL` | Optional Better Auth origin override. Known template or request context, `APP_URL`, and platform metadata such as Netlify or Vercel are used when it is unset. | An absolute public `http(s)` origin. | | `BETTER_AUTH_TRUSTED_ORIGINS` | Exact browser origins trusted by Better Auth, including configured host aliases. | A comma-separated list of absolute `http(s)` origins; wildcards are not accepted. | | `APP_BASE_PATH` | Mounts an app under a path such as `/mail`. | Unset for a standalone app, or a slash-prefixed path. | | `PORT` | Local Node/Nitro server port. | A decimal TCP port. | | `NITRO_PRESET` | Build and deployment adapter. | A preset supported by the target host, such as `node`, `netlify`, `vercel`, or `cloudflare_module`. | | `BETTER_AUTH_SECRET` | Stable Better Auth session signing secret for standalone production apps. Workspace deploys can derive it from `A2A_SECRET`. | A fresh random value of at least 32 characters. | | `OAUTH_STATE_SECRET` | Dedicated signing key for OAuth state envelopes. Falls back to `BETTER_AUTH_SECRET` when unset. | A fresh random value of at least 32 characters. | | `A2A_SECRET` | Shared HMAC for trusted cross-app A2A calls and signed handoffs. | One shared random value across trusted apps. | | `SECRETS_ENCRYPTION_KEY` | Legacy app-local/shared encryption fallback. | A stable encryption key; prefer the workspace key for new shared vaults. | | `WORKSPACE_SECRETS_ENCRYPTION_KEY` | Stable encryption key for a workspace-shared secrets vault. | The same stable key in every app that reads the vault. | | `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS` | Previous workspace key during rotation. | The old key only; remove it after migration. | | `ANTHROPIC_API_KEY` | Shared fallback for self-hosted apps, including remote databases. | An Anthropic API key; saved personal, organization, or workspace-scoped keys take precedence. | | `AGENT_ENGINE` | Explicitly selects the agent engine instead of auto-detecting from provider keys. | A registered engine name such as `anthropic`, `ai-sdk:openai`, `builder`, or `codex-cli`. | | `AGENT_BUILT_IN_ENGINES` | Restricts which built-in engines are registered at all, so the rest never appear in the model picker or resolve by name. | A comma-separated list of built-in engine names such as `ai-sdk:openai`; unset registers every built-in. | | `AGENT_SOURCE_SWEEP_TOOL_CALL_THRESHOLD` | Read-only source/search tool calls one turn may make before the agent is told to converge and answer from what it gathered. | A positive integer; defaults to 24. Raise it for research-shaped apps that legitimately inspect many records. | | `AGENT_ENGINE_PREFER_BYO_KEY` | Prefers a provider key you set over the managed Builder gateway during auto-detection. | `true` or `1`; Builder still applies as the fallback when no provider key is set. | | `AUTH_MODE` | Selects the local authentication behavior used by CLI and agent flows. | Unset or `local`; this is not a browser login bypass. | | `AGENT_NATIVE_ALLOW_BUILDER_PREVIEW_LOCAL_DEV` | Explicitly enables the existing local-dev sign-in button on approved Builder preview hosts during development. | `1` or `true`; requires development mode and must stay off public or production deployments. | | `AUTH_DISABLED` | Disables auth for local or preview-only work. Unset already means false. | `true` or `1`; never use on a public production app. | | `AUTH_MAGIC_LINK` | Controls the password-first versus magic-link sign-in path. | `0` keeps password-first sign-in; otherwise a configured email transport can enable magic links. | | `AUTH_SKIP_EMAIL_VERIFICATION` | Skips signup email verification for local QA or previews. | `1`; never use it to weaken production auth. | | `AUTH_REQUIRE_EMAIL_VERIFICATION` | Declares whether password signup must verify the email address, in any environment. | `0` or `1`; outranks `AUTH_SKIP_EMAIL_VERIFICATION`. `0` accepts an unverified address as a login credential. | | `ACCESS_TOKEN` / `ACCESS_TOKENS` | Static bearer fallback for MCP and Connect clients. | One token or a delimited token list; these are not browser auth. | | `AGENT_PROD_CODE_EXECUTION` | Production code-execution policy. | `off`, `sandboxed`, or `trusted`. See [Production Code Execution](/docs/actions-agent-tools#production-code-execution). | | `AGENT_NATIVE_SSR_CACHE` | Deployment-wide public SSR shell cache policy. | Unset/`on`, `off`, or a duration such as `30s` or `5m`. See [SSR Caching](/docs/ssr-caching). | | `AGENT_NATIVE_HEAD_SCRIPT_SRC` | Extra script added to every server-rendered page head. Where the consent banner shows, it waits for analytics consent, like Google Analytics. | An absolute `https://` URL; non-HTTPS values fail config validation. | | `AGENT_NATIVE_ENABLE_KEEP_WARM` | Opts into the Netlify keep-warm scheduled function; unset by default. | `1`; see [Keep-warm](/docs/netlify#netlify-keep-warm). | | `AGENT_NATIVE_DISABLE_KEEP_WARM` | Compatibility kill switch for the Netlify keep-warm scheduled function. | `1`; see [Keep-warm](/docs/netlify#netlify-keep-warm). | | `AGENT_NATIVE_KEEP_WARM_SCHEDULE` | Keep-warm cadence override when enabled. | A 5-field cron expression such as `*/5 * * * *`; an unparseable value fails the build. | | `AGENT_NATIVE_DISABLE_KEEP_WARM_BACKGROUND` | Drops only the background-function warm and keeps the server warm when keep-warm is enabled. | `1`; see [Keep-warm](/docs/netlify#netlify-keep-warm). | | `AGENT_NATIVE_DISABLE_INPROCESS_SWEEPS` | Turns off the in-process backstop sweep timers where a durable scheduler drives the same work. | `1`; queued work is not retried without another driver. | | `CRON_SECRET` | Bearer secret Vercel sends with cron requests; the scheduled sweep rejects requests without it. | A fresh random value; see [Scheduled work](/docs/vercel#vercel-scheduled-work). | | `AGENT_NATIVE_VERCEL_CRON_SCHEDULE` | Build-time cadence for the Vercel sweep cron job. | A 5-field cron expression, default `* * * * *`; a daily one such as `0 9 * * *` on Hobby. | | `AGENT_NATIVE_SKIP_ENSURE_TABLES` | Skips on-demand schema DDL for an already-migrated database. | `1`; see [On-demand schema DDL](/docs/deployment#skip-ensure-tables). You own migrations when this is set. | | `COOKIE_DOMAIN` | Shares auth cookies across same-database subdomains when explicitly configured. | A cookie domain. | | `CORS_ALLOWED_ORIGINS` | Cross-origin request allowlist. | A comma-separated list of exact origins. | | `AGENT_NATIVE_SELF_DISPATCH_URL` | Where this deployment sends its own background work, ahead of the platform URLs and `APP_URL`. Lets a long-lived server dispatch over loopback instead of its edge. | An absolute `http(s)` URL such as `http://127.0.0.1:3000`; the app base path is appended. | | `WEBHOOK_BASE_URL` | Optional public base URL for self-callback and webhook targets. | An absolute public `http(s)` origin. | | `APP_NAME` | App identity used by workspace and app-scoped configuration. | A short app name, such as `mail`. | | `APP_ID` / `APP_TEMPLATE` | Optional app identity and generated-template metadata. | App-owned strings. | | `NODE_ENV` | Node runtime mode. | Normally `development`, `test`, or `production`. | | `CI` | Marks CI-driven test and build behavior. | A CI-provided truthy value. | | `DEBUG` | Enables resolver-specific debug logging. | A resolver-supported truthy or namespace value. | Generate strong secrets with: ```bash openssl rand -hex 32 ``` ## What a normal deployment actually needs Do not copy a five-variable auth checklist into every app. The framework defaults `AUTH_DISABLED` to false and infers `BETTER_AUTH_URL` from known template/request context and hosting platform metadata. A standalone production app normally needs only one auth-specific deploy secret, `BETTER_AUTH_SECRET`, plus a persistent PostgreSQL URL. Workspace deployments can use the already-required `A2A_SECRET` to derive the Better Auth secret and trusted internal signing keys. Local development intentionally uses PGlite when no database URL is present and generates a Better Auth secret when no local secret is configured, persisting it at `/.agent-native/dev-auth-secret` so local sign-in survives dev-server restarts. Those fallbacks keep `pnpm dev` zero-setup, but they are not silently accepted as production configuration. The build and runtime diagnostics report missing or weak auth/A2A secrets, local databases, auth disabled in production, invalid public origins, and app-declared required keys without including any secret values. Every framework app exposes the redacted report at `/_agent-native/ping?configuration=1`. The shared provider shell turns a non-healthy production report into a warning or error chip with a **Copy prompt for AI** button. `agent-native.config.ts` or its compatibility aliases can add non-secret requirements under `runtime.environment.required`; set the actual values in Netlify, Vercel, or the deployment's secret store. ## Google sign-in Set one complete Google OAuth client pair to show the Google sign-in flow. Prefer a low-scope identity-only client for app login, and keep API access in a separate connection when a product needs broader Google scopes. | Variable | What it controls | Supported values or format | | ------------------------------ | ----------------------------------------------------------------------------------------------- | ----------------------------------------- | | `GOOGLE_SIGN_IN_CLIENT_ID` | Preferred low-scope Google OAuth client ID for app login. | The client ID from Google Cloud Console. | | `GOOGLE_SIGN_IN_CLIENT_SECRET` | Secret for the preferred sign-in client. | The matching client secret. | | `GOOGLE_CLIENT_ID` | Backwards-compatible sign-in fallback and provider OAuth client ID for Google API integrations. | The matching Google OAuth client ID. | | `GOOGLE_CLIENT_SECRET` | Secret for `GOOGLE_CLIENT_ID`. | The matching client secret. | | `GOOGLE_AUTH_MODE` | Chooses the sign-in interaction. | `auto` (default), `popup`, or `redirect`. | Register the callback URL in Google Cloud Console as the app's public URL, including its base path, followed by `/_agent-native/google/callback`. See [Authentication - Google OAuth](/docs/authentication#social-providers). `GOOGLE_LEGACY_CLIENT_ID` and `GOOGLE_LEGACY_CLIENT_SECRET` are accepted for older Google provider connections. `GOOGLE_SERVICE_ACCOUNT_KEY` and `GOOGLE_APPLICATION_CREDENTIALS` are server-side service-account options for specific Google API integrations; they are not required for browser sign-in. ## LLM provider keys {#llm-provider-keys} Use a provider key for local development or as an app-wide fallback on a self-hosted deployment. You can also connect with **Use Builder.io** or add a personal or organization key through **Custom keys** in the app. - **Local development:** Add the key to the app's `.env` file before running `pnpm dev`. - **Self-hosted fallback:** Set the key in the server-side environment. Signed-in users without a personal, organization, or workspace key can use it, and usage is billed to the deployment account. Scoped keys take precedence. Anonymous public runs and synthetic traffic do not use the fallback. Production Hosted-workspace runtimes block it. - **Scoped key:** **Custom keys** stores personal or organization credentials in the app's encrypted database-backed credential store. - **Builder connection:** **Use Builder.io** uses the managed Builder connection instead of one of these provider keys. Choose the model in Settings. `OPENAI_BASE_URL` configures an OpenAI-compatible endpoint and is used with `OPENAI_API_KEY`. | Variable | What it controls | Format | | ------------------------------ | ------------------------------------------------ | --------------------------------------------------- | | `ANTHROPIC_API_KEY` | Anthropic Claude model fallback. | Anthropic API key | | `OPENAI_API_KEY` | OpenAI model fallback. | OpenAI API key | | `OPENROUTER_API_KEY` | OpenRouter model fallback. | OpenRouter API key | | `OPENAI_BASE_URL` | OpenAI-compatible endpoint for `OPENAI_API_KEY`. | Absolute `http(s)` URL without embedded credentials | | `GOOGLE_GENERATIVE_AI_API_KEY` | Google Gemini model fallback. | Google AI API key | Additional provider variables are listed in the [full environment-variable inventory on GitHub](https://github.com/BuilderIO/agent-native/blob/main/docs/environment-variables.md#authentication-provider-and-integration-variables). ## Search and email fallbacks These optional keys provide web search or transactional email for apps that use those features. | Variable | What it controls | Format | | ------------------------------ | ------------------------------------------ | ----------------------------------- | | `BRAVE_SEARCH_API_KEY` | Brave web search. | Brave Search API key | | `TAVILY_API_KEY` | Tavily web search. | Tavily API key | | `EXA_API_KEY` | Exa web search. | Exa API key | | `FIRECRAWL_API_KEY` | Firecrawl web search. | Firecrawl API key | | `RESEND_API_KEY` | Resend transactional email delivery. | Resend API key | | `SENDGRID_API_KEY` | SendGrid transactional email delivery. | SendGrid API key | | `EMAIL_FROM` | Sender address for transactional email. | Valid email or display-name address | | `EMAIL_AGENT_ADDRESS` | Inbound address for email-enabled apps. | Valid email address | | `EMAIL_INBOUND_WEBHOOK_SECRET` | Verifies inbound email webhook signatures. | Stable random secret | ## Per-app values in a workspace The workspace root `.env` is loaded into every app. An app-local file such as `apps/mail/.env` wins when the same key exists in both places, so use the root file for shared values and the app file for app-specific values. Some deploy-level values also support an app-name prefix. Set `APP_NAME`, uppercase it, and replace non-alphanumeric characters with `_`: ```bash APP_NAME=mail MAIL_DATABASE_URL= MAIL_SECRETS_ENCRYPTION_KEY= ``` The prefix form is supported for database URLs and app-local secret encryption. Do not invent a prefix for an arbitrary variable; use `apps//.env` or the shared root `.env` according to the variable's scope. ## Public versus secret values Variables whose names start with `VITE_` and values read through `import.meta.env` can be bundled into browser code. Treat them as public configuration. Never put an API key, token, password, or private key in a browser-exposed variable. Advanced integration and host-detection keys stay with their owning feature guides and the maintainer inventory rather than appearing as a generic setup block here. Use a scoped workspace connection for user or provider credentials, and follow the owning app or feature guide when one is actually needed. See [Security](/docs/security) for the credential boundary and [Deployment](/docs/deployment) for production hosting. ## Keeping the reference complete The maintainer-only repository inventory remains broader than this public page. Run the focused check from the repository root when adding a framework variable: ```bash pnpm run guard:env-documentation ``` The check keeps the exhaustive internal inventory aligned with source while also checking that the curated setup tables above do not omit a key they explicitly document.