Environment configuration

Keep one configuration source per environment. Local development, serving processes, and database administration have different credential needs.

Shared local configuration

The API and dispatcher read the same .env; exported variables take precedence. For free simulation use EXECUTION_PROVIDER=simulator. For native Docker use PLATFORM_MODE=local, EXECUTION_PROVIDER=docker, and ORCHESTRATION_BACKEND=poller; keep inference disabled until a budget is approved. The Docker command aliases validate these settings rather than load a second overlay. Restart both processes after a configuration change. DOCKER_RUNTIME_IMAGE selects a locally built image and DOCKER_NETWORK an optional bridge. Keep hosted credentials separate. Follow the Docker guide for model/BYOK setup, costs and acceptance.

Where settings belong

Use .env.example as the setting inventory, not as a production-ready secret file. No .data worksheet or developer-specific helper is required. Avoid multiple .env.local files that give Next.js and command-line workers different values.

Store private files outside version control with owner-only permissions. Parse dotenv files with Node or a dotenv reader rather than sourcing arbitrary text as shell code. Existing exported variables can override env-file values; use a clean administrative shell for migration commands.

Staging and Vercel project selection

1. Use a dedicated staging Vercel project with a stable HTTPS origin. Configure an isolated database, private R2 bucket, identity sender, secrets, and Stripe test ledger. A normal database branch can copy production data and credentials; prefer a schema-only branch or new database with synthetic accounts.
2. For a dedicated staging project, put its staging runtime settings in that project's Production environment and deploy to its production URL. Vercel's environment label describes the deployment target within that project, not whether it serves real customers. This also lets staging exercise the production deployment's Cron behavior. Configure Preview deployments separately with non-production resources.
3. Before importing variables or deploying, verify the selected Vercel team, project, environment, and origin. Check command selection, VERCEL_PROJECT_ID/VERCEL_ORG_ID, and local .vercel links for conflicts. Explicitly select staging instead of relying on a root .env or previous CLI link that may select production. Vercel CLI project selection.
4. Reuse a valid Vercel CLI login for interactive administration. VERCEL_TOKEN authenticates API/CLI automation; it is not an application secret or the runtime's Sandbox identity. Unattended tooling can use a separately managed, expiring token with the intended team scope. Keep it in the tooling secret store, outside the web runtime and agent image. Vercel access tokens.
5. Confirm the database, bucket, sender, Stripe account/mode, price IDs, and callback destinations by identity and behavior. A count of saved environment variables is not a readiness check. Finish Stripe activation after deployment.

Application and identity

For rotation, configure VAULT_ACTIVE_KEY_ID and VAULT_KEYRING_JSON, retain old decrypt keys, rehearse restoration, and use the reviewed rewrap procedure. Do not replace the only copy of an old key.

Database and storage

See database setup and hosting. Database backups alone cannot restore encrypted project content.

The migration identity must own the target schemas and have CREATEROLE plus ADMIN OPTION on existing runtime/reporting roles. PostgreSQL 16+ requires that authority to install per-database runtime deadlines. Keep it in the administrative environment; the serving identity remains restricted.

Execution and admission

The Sandbox adapter currently uses Vercel OIDC. Static VERCEL_TOKEN, team, and project fields do not enable production execution on another host by themselves.

All schedulers must use matching fleet settings. The old shared WORKER_CONCURRENCY setting is removed. See capacity settings for database, Workflow, maintenance, HTTP and pending-work controls. Apply migration 051 before deploying the matching dispatcher.

Worker offerings

Hosted server-backed Workers are enabled with RENDER_WORKER_ENABLED=true only after configuring the Render account, owner, compatible immutable image, supported service plan/region, and reviewed RENDER_COMPUTE_MICRO_USD_PER_MINUTE. The Worker operations guide owns accepted quotes, capability validation, funding, and shutdown verification. A Worker price or lifecycle setting does not replace provider quotas or deployment-wide admission limits.

Models, tools, and billing

Managed models use OPENAI_API_KEY, ANTHROPIC_API_KEY, or OPENROUTER_API_KEY, with the built-in catalog supplying enabled models, compatible harnesses, provider routes, and reviewed rates. Catalog data and price-version hashes are application state, not environment variables.

Optional Composio settings are COMPOSIO_API_KEY, COMPOSIO_CALLBACK_VERIFICATION_ENABLED, and COMPOSIO_MICRO_USD_PER_CALL. Toolkit auth-config IDs and exact versions are persisted with connector setup. MCP uses reviewed MCP_STDIO_CATALOG_JSON and optional exact-origin MCP_OAUTH_CLIENTS_JSON. Managed search uses BRAVE_SEARCH_API_KEY and BRAVE_SEARCH_MICRO_USD_PER_CALL. Other supported search providers use customer connections.

GitHub repository access uses GITHUB_APP_ID, GITHUB_APP_SLUG, GITHUB_APP_CLIENT_ID, GITHUB_APP_CLIENT_SECRET, GITHUB_APP_PRIVATE_KEY, and GITHUB_WEBHOOK_SECRET. Optional social login uses separate GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET values.

Stripe uses STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_PRO_PRICE_ID, and STRIPE_SCALE_PRICE_ID. Align recurring prices with the PRO_* and SCALE_* display and included-credit fields in .env.example. Keep test and live accounts, destinations, and ledgers separate.

Optional PostHog exports require POSTHOG_ENABLED, region, project token, start time, and a daily event budget. They are disabled by default and are not needed for native reporting.

Apply and validate

Import only runtime fields into the matching hosting environment, then redeploy. Use the administrative environment only for migrations and provisioning. Verify origin, role restrictions, readiness, and callbacks without printing secrets. The deployment guide provides the ordered steps; provider integrations explains external setup.