Skip to content

BuilderIO/agent-native / packages/core/docs

agent-native-docs

Unverified

How to look up version-matched Agent-Native framework docs and source in node_modules. Use before coding against @agent-native/core APIs or advanced features.

FileKindSize
AGENTS.mdmarkdown6.0 KB
SKILL.mdskill md2.2 KB
content/a2a-protocol.mdxmarkdown37.6 KB
content/actions-access-control.mdxmarkdown28.9 KB
content/actions-advanced.mdxmarkdown13.1 KB
content/actions-agent-tools.mdxmarkdown5.6 KB
content/actions-defining.mdxmarkdown31.2 KB
content/actions-other-surfaces.mdxmarkdown10.3 KB
content/actions-overview.mdxmarkdown8.3 KB
content/actions-run-context.mdxmarkdown9.1 KB
content/add-ui-to-your-agent.mdxmarkdown5.0 KB
content/administered-deployments.mdxmarkdown7.7 KB
content/agent-mentions.mdxmarkdown10.2 KB
content/agent-native-config.mdxmarkdown34.9 KB
content/agent-native-toolkit.mdxmarkdown17.3 KB
content/agent-resources.mdxmarkdown27.0 KB
content/agent-surfaces.mdxmarkdown33.8 KB
content/agent-teams.mdxmarkdown13.4 KB
content/agent-web-surfaces.mdxmarkdown10.7 KB
content/agentkit.mdxmarkdown14.0 KB
content/audit-log.mdxmarkdown14.3 KB
content/authentication.mdxmarkdown30.7 KB
content/automation-connectors.mdxmarkdown7.8 KB
content/automations.mdxmarkdown26.7 KB
content/aws-amplify.mdxmarkdown10.7 KB
content/aws-lambda.mdxmarkdown13.9 KB
content/aws-rds.mdxmarkdown1.7 KB
content/azure-postgresql.mdxmarkdown1.8 KB
content/azure-static-web-apps.mdxmarkdown9.1 KB
content/blueprint-installer.mdxmarkdown6.3 KB
content/cli-adapters.mdxmarkdown5.7 KB
content/client-advanced.mdxmarkdown13.1 KB
content/client-agent-chat.mdxmarkdown17.7 KB
content/client-data.mdxmarkdown19.3 KB
content/client-entry-points.mdxmarkdown1.2 KB
content/client-overview.mdxmarkdown10.6 KB
content/client-routing.mdxmarkdown5.7 KB
content/client-sync-internals.mdxmarkdown5.2 KB
content/cloneable-saas.mdxmarkdown16.6 KB
content/cloud-sql.mdxmarkdown2.3 KB
content/cloudflare.mdxmarkdown8.3 KB
content/code-agents-ui.mdxmarkdown26.6 KB
content/components.mdxmarkdown42.9 KB
content/context-awareness.mdxmarkdown24.9 KB
content/create-with-an-agent.mdxmarkdown8.8 KB
content/creating-templates.mdxmarkdown21.6 KB
content/cross-app-connect-design.mdxmarkdown8.4 KB
content/cross-app-sso.mdxmarkdown8.7 KB
content/custom-design-system.mdxmarkdown17.3 KB
content/data-programs.mdxmarkdown25.0 KB
content/decisions.mdxmarkdown7.9 KB
content/deno-deploy.mdxmarkdown7.2 KB
content/deploy-an-app.mdxmarkdown5.0 KB
content/deployment-environment-variables.mdxmarkdown16.3 KB
content/deployment.mdxmarkdown11.3 KB
content/dispatch.mdxmarkdown18.6 KB
content/docker.mdxmarkdown8.1 KB
content/docs-components.mdxmarkdown28.9 KB
content/doctor.mdxmarkdown21.3 KB
content/drafts/clips-experimental-features.mdmarkdown5.4 KB
content/drop-in-agent.mdxmarkdown16.0 KB
content/durable-background-runs.mdxmarkdown13.8 KB
content/durable-resume.mdxmarkdown10.0 KB
content/embedding-sdk.mdxmarkdown31.3 KB
content/environment-variables.mdxmarkdown29.9 KB
content/evals.mdxmarkdown12.4 KB
content/extensions.mdxmarkdown34.8 KB
content/external-agents-catalog.mdxmarkdown40.5 KB
content/external-agents.mdxmarkdown29.3 KB
content/file-uploads.mdxmarkdown10.7 KB
content/generative-ui.mdxmarkdown10.8 KB
content/getting-started-actions.mdxmarkdown2.7 KB
content/getting-started-pages.mdxmarkdown2.6 KB
content/getting-started.mdxmarkdown7.2 KB
content/harness-agents.mdxmarkdown16.9 KB
content/http-api.mdxmarkdown20.9 KB
content/integrations.mdxmarkdown33.8 KB
content/internationalization.mdxmarkdown6.2 KB
content/key-concepts.mdxmarkdown30.6 KB
content/koyeb.mdxmarkdown7.3 KB
content/locales/ar-SA/a2a-protocol.mdxmarkdown48.5 KB
content/locales/ar-SA/actions-access-control.mdxmarkdown40.8 KB
content/locales/ar-SA/actions-advanced.mdxmarkdown16.3 KB
content/locales/ar-SA/actions-agent-tools.mdxmarkdown8.1 KB
content/locales/ar-SA/actions-defining.mdxmarkdown42.2 KB
content/locales/ar-SA/actions-other-surfaces.mdxmarkdown14.5 KB
content/locales/ar-SA/actions-overview.mdxmarkdown11.3 KB
content/locales/ar-SA/actions-run-context.mdxmarkdown11.1 KB
content/locales/ar-SA/add-ui-to-your-agent.mdxmarkdown3.7 KB
content/locales/ar-SA/administered-deployments.mdxmarkdown6.4 KB
content/locales/ar-SA/agent-mentions.mdxmarkdown11.8 KB
content/locales/ar-SA/agent-native-toolkit.mdxmarkdown17.3 KB
content/locales/ar-SA/agent-resources.mdxmarkdown36.8 KB
content/locales/ar-SA/agent-surfaces.mdxmarkdown48.4 KB
content/locales/ar-SA/agent-teams.mdxmarkdown18.5 KB
content/locales/ar-SA/agent-web-surfaces.mdxmarkdown14.3 KB
content/locales/ar-SA/audit-log.mdxmarkdown15.9 KB
content/locales/ar-SA/authentication.mdxmarkdown39.8 KB
content/locales/ar-SA/automations.mdxmarkdown31.3 KB
content/locales/ar-SA/aws-amplify.mdxmarkdown14.9 KB
content/locales/ar-SA/aws-lambda.mdxmarkdown18.9 KB
content/locales/ar-SA/aws-rds.mdxmarkdown319 B
content/locales/ar-SA/azure-postgresql.mdxmarkdown344 B
content/locales/ar-SA/azure-static-web-apps.mdxmarkdown12.4 KB
content/locales/ar-SA/blueprint-installer.mdxmarkdown8.4 KB
content/locales/ar-SA/cli-adapters.mdxmarkdown6.7 KB
content/locales/ar-SA/client-advanced.mdxmarkdown17.8 KB
content/locales/ar-SA/client-agent-chat.mdxmarkdown23.0 KB
content/locales/ar-SA/client-data.mdxmarkdown23.8 KB
content/locales/ar-SA/client-entry-points.mdxmarkdown1.6 KB
content/locales/ar-SA/client-overview.mdxmarkdown13.9 KB
content/locales/ar-SA/client-routing.mdxmarkdown7.2 KB
content/locales/ar-SA/client-sync-internals.mdxmarkdown7.3 KB
content/locales/ar-SA/cloneable-saas.mdxmarkdown23.2 KB
content/locales/ar-SA/cloud-sql.mdxmarkdown317 B
content/locales/ar-SA/cloudflare.mdxmarkdown11.9 KB
content/locales/ar-SA/code-agents-ui.mdxmarkdown34.2 KB
content/locales/ar-SA/components.mdxmarkdown51.5 KB
content/locales/ar-SA/context-awareness.mdxmarkdown33.1 KB
content/locales/ar-SA/create-with-an-agent.mdxmarkdown12.2 KB
content/locales/ar-SA/creating-templates.mdxmarkdown26.8 KB
content/locales/ar-SA/cross-app-connect-design.mdxmarkdown1.5 KB
content/locales/ar-SA/cross-app-sso.mdxmarkdown9.7 KB
content/locales/ar-SA/custom-design-system.mdxmarkdown21.6 KB
content/locales/ar-SA/data-programs.mdxmarkdown33.3 KB
content/locales/ar-SA/decisions.mdxmarkdown9.1 KB
content/locales/ar-SA/deno-deploy.mdxmarkdown10.1 KB
content/locales/ar-SA/deploy-an-app.mdxmarkdown7.1 KB
content/locales/ar-SA/deployment-environment-variables.mdxmarkdown21.3 KB
content/locales/ar-SA/deployment.mdxmarkdown13.9 KB
content/locales/ar-SA/dispatch.mdxmarkdown27.3 KB
content/locales/ar-SA/docker.mdxmarkdown11.3 KB
content/locales/ar-SA/doctor.mdxmarkdown3.4 KB
content/locales/ar-SA/drop-in-agent.mdxmarkdown20.8 KB
content/locales/ar-SA/durable-resume.mdxmarkdown15.4 KB
content/locales/ar-SA/embedding-sdk.mdxmarkdown41.3 KB
content/locales/ar-SA/evals.mdxmarkdown13.3 KB
content/locales/ar-SA/extensions.mdxmarkdown34.0 KB
content/locales/ar-SA/external-agents.mdxmarkdown89.3 KB
content/locales/ar-SA/file-uploads.mdxmarkdown13.4 KB
content/locales/ar-SA/getting-started-actions.mdxmarkdown3.2 KB
content/locales/ar-SA/getting-started-pages.mdxmarkdown3.2 KB
content/locales/ar-SA/getting-started.mdxmarkdown9.7 KB
content/locales/ar-SA/harness-agents.mdxmarkdown22.3 KB
content/locales/ar-SA/internationalization.mdxmarkdown8.2 KB
content/locales/ar-SA/key-concepts.mdxmarkdown42.0 KB
content/locales/ar-SA/koyeb.mdxmarkdown10.2 KB
content/locales/ar-SA/mcp-apps.mdxmarkdown33.7 KB
content/locales/ar-SA/mcp-clients.mdxmarkdown35.0 KB
content/locales/ar-SA/mcp-protocol.mdxmarkdown27.6 KB
content/locales/ar-SA/messaging.mdxmarkdown59.2 KB
content/locales/ar-SA/multi-app-workspace.mdxmarkdown36.2 KB
content/locales/ar-SA/multi-tenancy.mdxmarkdown7.5 KB
content/locales/ar-SA/native-chat-ui.mdxmarkdown21.3 KB
content/locales/ar-SA/neon.mdxmarkdown244 B
content/locales/ar-SA/netlify.mdxmarkdown15.2 KB
content/locales/ar-SA/node-docker.mdxmarkdown878 B
content/locales/ar-SA/node-js.mdxmarkdown8.4 KB
content/locales/ar-SA/notifications.mdxmarkdown16.2 KB
content/locales/ar-SA/observability.mdxmarkdown45.2 KB
content/locales/ar-SA/observational-memory.mdxmarkdown10.9 KB
content/locales/ar-SA/onboarding.mdxmarkdown16.9 KB
content/locales/ar-SA/organizations-teams-permissions.mdxmarkdown5.9 KB
content/locales/ar-SA/package-lifecycle.mdxmarkdown3.0 KB
content/locales/ar-SA/plan-plugin.mdxmarkdown23.0 KB
content/locales/ar-SA/portal.mdxmarkdown636 B
content/locales/ar-SA/postgres.mdxmarkdown487 B
content/locales/ar-SA/pr-visual-recap.mdxmarkdown53.9 KB
content/locales/ar-SA/privacy-and-data-rights.mdxmarkdown6.2 KB
content/locales/ar-SA/processors.mdxmarkdown8.7 KB
content/locales/ar-SA/progress.mdxmarkdown10.7 KB
content/locales/ar-SA/pure-agent-apps.mdxmarkdown5.0 KB
content/locales/ar-SA/real-time-collaboration.mdxmarkdown55.6 KB
content/locales/ar-SA/recorder.mdxmarkdown16.7 KB
content/locales/ar-SA/recurring-jobs.mdxmarkdown23.8 KB
content/locales/ar-SA/render.mdxmarkdown11.2 KB
content/locales/ar-SA/sandbox-adapters.mdxmarkdown18.0 KB
content/locales/ar-SA/security.mdxmarkdown31.5 KB
content/locales/ar-SA/server-database.mdxmarkdown27.6 KB
content/locales/ar-SA/server-middleware.mdxmarkdown7.9 KB
content/locales/ar-SA/server-overview.mdxmarkdown12.2 KB
content/locales/ar-SA/server-plugins.mdxmarkdown9.1 KB
content/locales/ar-SA/server-routes.mdxmarkdown14.3 KB
content/locales/ar-SA/sharing.mdxmarkdown28.6 KB
content/locales/ar-SA/skills-guide.mdxmarkdown27.0 KB
content/locales/ar-SA/ssr-caching.mdxmarkdown7.4 KB
content/locales/ar-SA/supabase.mdxmarkdown264 B
content/locales/ar-SA/syncing-template-changes.mdxmarkdown11.7 KB
content/locales/ar-SA/telemetry.mdxmarkdown21.9 KB
content/locales/ar-SA/template-analytics.mdxmarkdown26.4 KB
content/locales/ar-SA/template-assets.mdxmarkdown31.9 KB
content/locales/ar-SA/template-brain.mdxmarkdown29.7 KB
content/locales/ar-SA/template-calendar-agent.mdxmarkdown10.2 KB
content/locales/ar-SA/template-calendar-developers.mdxmarkdown33.4 KB
content/locales/ar-SA/template-calendar-features.mdxmarkdown14.4 KB
content/locales/ar-SA/template-calendar-integrations.mdxmarkdown6.2 KB
content/locales/ar-SA/template-calendar.mdxmarkdown4.4 KB
content/locales/ar-SA/template-chat-agent.mdxmarkdown4.7 KB
content/locales/ar-SA/template-chat-developers.mdxmarkdown31.3 KB
content/locales/ar-SA/template-chat-features.mdxmarkdown9.9 KB

content/environment-variables.mdx

View on GitHub
---
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_<PATH>` 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.

To select OpenRouter explicitly, set `AGENT_ENGINE=ai-sdk:openrouter` and configure its credential through a [workspace connection](/docs/workspace-connections). Model IDs use the provider/model form.

## 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`            |
| `billing.commercialSurfaces`   | `AGENT_NATIVE_CONFIG_BILLING_COMMERCIAL_SURFACES`  |
| `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 `<APP_NAME>_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). |
| `DO_NOT_TRACK`                                 | Set to `1` to turn off CLI [telemetry](/docs/telemetry), crash reports included.                                                                                               |
| `AGENT_NATIVE_TELEMETRY_DISABLED`              | Set to `1` to turn off CLI [telemetry](/docs/telemetry), crash reports included.                                                                                               |
| `AGENT_NATIVE_TELEMETRY_DEBUG`                 | Set to `1` to print each CLI telemetry event to stderr and send nothing.                                                                                                       |
| `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. Listed origins may send credentials, which a UI on another origin needs (see `runtime.apiBaseUrl`).                                            | 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 `<app>/.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_DATABASE_URL>
MAIL_SECRETS_ENCRYPTION_KEY=<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/<name>/.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.
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 197kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 197kUpdated Claude CodeCodexVerifiedInstall