Configure environment variables

Use .env.example for fake development, .env.live.example for loopback live development, and .env.server.example as the server template. Old adapter values and deployment variable names have no aliases.

Runtime and data services

Variable	Default	Purpose
`NEOBANK_ENVIRONMENT`	`development`	Select `development`, `test`, or `production`
`NEOBANK_DATABASE_URL`	SQLite development URL	SQLAlchemy database URL; live requires PostgreSQL
`NEOBANK_REDIS_URL`	`redis://localhost:6379/0`	API-only session and rate-limit Redis
`NEOBANK_TASK_QUEUE_URL`	`redis://localhost:6379/1`	Worker-and-scheduler-only Celery broker and result backend; production uses a separate Redis authority
`NEOBANK_SESSION_BACKEND`	`memory`	Select `memory` or `redis`; live requires `redis`
`NEOBANK_APP_NAME`	`Example Neobank`	Customer-visible product name and base for API, provider, and Auth0 resource names
`NEOBANK_APP_NAME_AR`	Empty	Optional Arabic product name; localized surfaces fall back to `NEOBANK_APP_NAME`
`NEOBANK_APP_MARK`	`N`	Short customer-visible text mark in the web shell
`NEOBANK_PUBLIC_ORIGIN`	`http://localhost:3000`	Customer application origin; live deployments use the same canonical HTTPS origin as the API, without a trailing slash
`NEOBANK_API_ORIGIN`	`http://localhost:8000`	API origin; live deployments use the same canonical HTTPS origin as the customer application, without a trailing slash
`NEOBANK_METRICS_TOKEN`	Empty	Internal metrics bearer token; production requires at least 32 characters
`NEOBANK_DEBUG_AUTH_ENABLED`	`false`	Enable local debug identity headers; production rejects it
`NEOBANK_TRUSTED_PROXY_IPS`	`127.0.0.1`	Comma-separated IP addresses or CIDR networks whose forwarded client headers Uvicorn may trust; production requires an explicit non-loopback boundary and rejects `*` and default routes

Auth0

Variable	Purpose
`NEOBANK_AUTH0_DOMAIN`	Auth0 tenant domain
`NEOBANK_AUTH0_CLIENT_ID`	Customer regular web application identifier
`NEOBANK_AUTH0_CLIENT_SECRET`	Customer application secret
`NEOBANK_AUTH0_OPS_CLIENT_ID`	Operator regular web application identifier
`NEOBANK_AUTH0_OPS_CLIENT_SECRET`	Operator application secret
`NEOBANK_AUTH0_AUDIENCE`	Agent API audience
`NEOBANK_AUTH0_CLAIM_NAMESPACE`	Deployment-owned HTTPS namespace without a trailing slash; role and actor claims append `/roles` and `/actor_type`
`NEOBANK_PROBLEM_TYPE_BASE`	Deployment-owned HTTPS problem-type base without a trailing slash; errors append `/<error code>`

NEOBANK_AUTH0_DOMAIN accepts a hostname only. Claim and problem namespaces reject credentials, query strings, fragments, trailing slashes, and Auth0-owned claim domains. Non-local live runtimes require every identity field explicitly. Production also rejects reserved examples and placeholders. GET /v1/public-config exposes only the application name, optional Arabic name, and mark. It never exposes Auth0 or Management API configuration.

Auth0 reconciliation

The ignored .env.auth0 file contains the runtime identity variables plus these fields:

Variable	Purpose
`AUTH0_CANONICAL_DOMAIN`	Canonical tenant hostname used for Management API calls
`AUTH0_MANAGEMENT_CLIENT_ID`	Dedicated Management API client identifier
`AUTH0_MANAGEMENT_CLIENT_SECRET`	Dedicated Management API client secret
`AUTH0_CONNECTION_NAME`	Existing database connection; the only connection the customer and operator applications may use
`AUTH0_OPERATOR_ROLE_ID`	Managed operator role ID written by reconciliation; leave blank before the first apply

Copy .env.auth0.example, set mode 0600, and follow Configure a dedicated Auth0 tenant. The repository ignores every non-example .env.* file. The reconciler requests short-lived Management API tokens; do not store a manually generated access token in this file.

Perflo

Variable	Required value in live mode
`NEOBANK_PERFLO_ADAPTER`	`live`
`NEOBANK_PERFLO_APP_URL`	`https://app.perflo.ai`
`NEOBANK_PERFLO_PERFOLIO_URL`	`https://api.perfolio.ai/api`
`NEOBANK_PERFLO_FIAT_URL`	`https://api-fiat.perfolio.ai/api`
`NEOBANK_PERFLO_CARDS_URL`	`https://api-cards.perfolio.ai`
`NEOBANK_PERFLO_AGENT_URL`	`https://agent-mode-backend-prod-merge.up.railway.app`

fake is the only other adapter value. Values such as demo, pilot, and partner fail validation.

Vault

Variable	Default	Purpose
`NEOBANK_VAULT_ADDR`	`http://localhost:8200`	Vault API address; production requires HTTPS
`NEOBANK_VAULT_CA_PATH`	empty	Optional private CA bundle used only for Vault TLS; public Perflo and Auth0 clients retain the system trust store
`NEOBANK_VAULT_TOKEN`	Empty	Restricted Transit application token; non-local live runtimes require at least 32 characters
`NEOBANK_VAULT_TRANSIT_KEY`	`neobank-perflo-credentials`	Derived Transit key
`NEOBANK_VAULT_TLS_DIR`	None	Server host directory containing `ca.pem`, `server.pem`, and `server-key.pem`

Server Compose

Variable	Purpose
`NEOBANK_HOST`	Public hostname served by Caddy
`CADDY_ACME_EMAIL`	Automatic Certificate Management Environment contact
`NEOBANK_POSTGRES_PASSWORD`	PostgreSQL server password; it must match the encoded password in `NEOBANK_DATABASE_URL`
`NEOBANK_API_PORT`	Loopback API port for local Compose only
`NEOBANK_WEB_PORT`	Loopback web port for local Compose only

Production also requires HTTPS application origins, disabled debug authentication, configured Auth0 applications, PostgreSQL, isolated session and task Redis authorities, authenticated metrics, and the exact reviewed Perflo origins. API workloads receive only NEOBANK_REDIS_URL; worker and scheduler workloads receive only NEOBANK_TASK_QUEUE_URL.

Get Started

Architecture

Deploy

Customize

Operate

Integrate

Security

Reference

Contributing

Environment variables

Configure environment variables

Runtime and data services

Auth0

Auth0 reconciliation

Perflo

Vault

Server Compose

​Configure environment variables

​Runtime and data services

​Auth0

​Auth0 reconciliation

​Perflo

​Vault

​Server Compose

Configure environment variables

Runtime and data services

Auth0

Auth0 reconciliation

Perflo

Vault

Server Compose