Configuration Reference

All configuration is handled by Pydantic Settings with the BEHAVRY_ prefix. Values can be set via environment variables or a .env file in the backend/ directory.

Core Settings

Variable	Default	Required	Description
`BEHAVRY_ENV`	`development`	No	`development` or `production`. Controls JWT auto-generation, debug routes, OpenAPI UI.
`BEHAVRY_DEBUG`	`false`	No	Enable verbose debug logging.

Database

Variable	Default	Required	Description
`BEHAVRY_DB_URL`	`postgresql+asyncpg://behavry:behavry@localhost:5432/behavry`	Yes	Async PostgreSQL connection string. Must use `asyncpg` driver.
`BEHAVRY_DB_POOL_SIZE`	`10`	No	SQLAlchemy connection pool size.
`BEHAVRY_DB_MAX_OVERFLOW`	`20`	No	Max connections above pool size during bursts.

Example:

BEHAVRY_DB_URL=postgresql+asyncpg://behavry:s3cr3t@db.internal:5432/behavry

OPA Policy Engine

Variable	Default	Required	Description
`BEHAVRY_OPA_URL`	`http://localhost:8181`	No	OPA sidecar base URL.
`BEHAVRY_OPA_TIMEOUT_SECONDS`	`2.0`	No	Per-request timeout for OPA calls. Keep low — this is in the agent's critical path.
`BEHAVRY_OPA_FAIL_CLOSED`	`true`	No	If `true`, OPA unreachability causes deny (safe default). Set `false` only for testing.

JWT / Auth

Variable	Default	Required in Prod	Description
`BEHAVRY_JWT_PRIVATE_KEY`	(auto-generated in dev)	Yes	RS256 private key PEM. Generate with `openssl genrsa -out private.pem 2048`.
`BEHAVRY_JWT_PUBLIC_KEY`	(auto-generated in dev)	Yes	RS256 public key PEM. Generate with `openssl rsa -in private.pem -pubout`.
`BEHAVRY_JWT_ALGORITHM`	`RS256`	No	JWT signing algorithm. Do not change.
`BEHAVRY_JWT_ISSUER`	`behavry`	No	JWT `iss` claim.
`BEHAVRY_APP_SECRET_KEY`	(random at startup)	No	Application-level secret for session cookies (if used). Set explicitly for multi-instance deployments.

Generating keys:

openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -pubout -out public.pem
# Paste PEM content into env vars (preserve newlines)
export BEHAVRY_JWT_PRIVATE_KEY="$(cat private.pem)"
export BEHAVRY_JWT_PUBLIC_KEY="$(cat public.pem)"

Admin Auth

Variable	Default	Required	Description
`BEHAVRY_ADMIN_USERNAME`	`admin`	No	Username for the default tenant admin created on first run.
`BEHAVRY_ADMIN_PASSWORD`	(empty — uses `admin` in dev)	Yes in prod	Password for the default admin. In dev, defaults to `admin`. Must be set in production.
`BEHAVRY_AUTH_PROVIDER`	`password`	No	Auth backend: `password`, `clerk`, or `oidc`.

Clerk OIDC (when `BEHAVRY_AUTH_PROVIDER=clerk`)

Variable	Default	Required	Description
`BEHAVRY_CLERK_SECRET_KEY`	(empty)	Yes	Clerk backend API key (`sk_live_...` or `sk_test_...`).
`BEHAVRY_CLERK_PUBLISHABLE_KEY`	(empty)	No	Clerk publishable key (frontend use, informational in backend).
`BEHAVRY_CLERK_ISSUER`	(empty)	Yes	Clerk issuer URL, e.g. `https://clerk.your-instance.clerk.accounts.dev`.

Frontend also requires:

VITE_CLERK_PUBLISHABLE_KEY=pk_live_...  # Set in dashboard/.env

Generic OIDC (when `BEHAVRY_AUTH_PROVIDER=oidc`)

Variable	Default	Required	Description
`BEHAVRY_OIDC_JWKS_URI`	(empty)	Yes	JWKS endpoint, e.g. `https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys`.
`BEHAVRY_OIDC_ISSUER`	(empty)	Yes	Token issuer, e.g. `https://login.microsoftonline.com/{tenant}/v2.0`.
`BEHAVRY_OIDC_AUDIENCE`	(empty)	No	Expected `aud` claim. Leave empty to skip audience verification.

CORS

Variable	Default	Required	Description
`BEHAVRY_CORS_ORIGINS_STR`	`http://localhost:3000,http://localhost:5173`	No	Comma-separated list of allowed CORS origins. Set to your dashboard URL in production.

Example:

BEHAVRY_CORS_ORIGINS_STR=https://app.behavry.com,https://behavry-alpha.fly.dev

SSE

Variable	Default	Description
`BEHAVRY_SSE_KEEPALIVE_SECONDS`	`15`	Interval for SSE keep-alive comments. Prevents proxy timeouts.

Webhooks / SIEM

Variable	Default	Description
`BEHAVRY_WEBHOOK_URL`	(empty)	Comma-separated outbound webhook URLs (Slack, Teams, Splunk HEC, etc.).
`BEHAVRY_WEBHOOK_SECRET`	(empty)	HMAC-SHA256 signing secret. Included in `X-Behavry-Signature` header.
`BEHAVRY_WEBHOOK_MIN_SEVERITY`	`high`	Minimum alert severity to trigger delivery: `low`, `medium`, `high`, `critical`.
`BEHAVRY_WEBHOOK_FORMAT`	`json`	Payload format: `json` or `cef` (Common Event Format for SIEM).

Demo / External Integrations

Variable	Required	Description
`GITHUB_TOKEN`	Demo only	GitHub PAT for GitHub MCP server demo.
`SLACK_BOT_TOKEN`	Demo only	Slack bot token for Slack MCP server demo.
`ANTHROPIC_API_KEY`	Demo only	Anthropic API key for Claude agent demo.
`OPENAI_API_KEY`	Demo only	OpenAI API key for ChatGPT agent demo.

Ollama Proxy

Variable	Default	Required	Description
`BEHAVRY_OLLAMA_URL`	`http://localhost:11434`	No	Upstream Ollama server URL for the Ollama API proxy.

Deployment Mode (Sprint W)

These variables control the control-plane / data-plane split for hybrid deployments.

Variable	Default	Required	Description
`BEHAVRY_DEPLOYMENT_MODE`	`standalone`	No	`standalone`, `control-plane`, or `data-plane`.
`BEHAVRY_CONTROL_PLANE_URL`	(empty)	data-plane	URL of the control plane (e.g. `https://control.behavry.com`).
`BEHAVRY_DATA_PLANE_TOKEN`	(empty)	data-plane	Token issued by the control plane for authentication.
`BEHAVRY_LICENSE_KEY`	(empty)	data-plane	License key for data plane validation.
`BEHAVRY_DEPLOYMENT_ID`	(empty)	data-plane	Unique ID for this data plane instance.
`BEHAVRY_HEARTBEAT_INTERVAL`	`60`	No	Seconds between heartbeats to the control plane.

Example (data plane):

BEHAVRY_DEPLOYMENT_MODE=data-plane
BEHAVRY_CONTROL_PLANE_URL=https://control.behavry.com
BEHAVRY_DATA_PLANE_TOKEN=dp_abc123...
BEHAVRY_LICENSE_KEY=lic_xyz789...
BEHAVRY_DEPLOYMENT_ID=dp-us-east-1-01
BEHAVRY_HEARTBEAT_INTERVAL=60

Data Protection (Sprint DP)

Variable	Default	Required	Description
`BEHAVRY_LOCAL_ENCRYPTION_KEY`	(empty)	encrypted mode	Base64-encoded 32-byte AES-256 key for the local KMS provider. Required when data protection mode is `encrypted`.

Generating a key:

python3 -c "import os, base64; print(base64.b64encode(os.urandom(32)).decode())"

Observability (Sprint O)

Variable	Default	Required	Description
`BEHAVRY_SENTRY_DSN`	(empty)	No	Sentry DSN. Omit or leave empty to disable (zero overhead).
`BEHAVRY_RELEASE_VERSION`	(empty)	No	Git SHA for Sentry release tracking. Set `BUILD_SHA` in Docker build args.
`BEHAVRY_METRICS_TOKEN`	(empty)	No	Bearer token for the `/metrics` endpoint. Empty = no auth (dev default).

Complete Minimal `.env` for Local Dev

BEHAVRY_ENV=development
BEHAVRY_ADMIN_PASSWORD=admin
BEHAVRY_DB_URL=postgresql+asyncpg://behavry:behavry@localhost:5432/behavry
BEHAVRY_OPA_URL=http://localhost:8181

Complete `.env` for Production (Standalone)

BEHAVRY_ENV=production
BEHAVRY_ADMIN_USERNAME=admin
BEHAVRY_ADMIN_PASSWORD=<strong-password>

# Database
BEHAVRY_DB_URL=postgresql+asyncpg://behavry:<db-password>@db:5432/behavry
BEHAVRY_DB_POOL_SIZE=10
BEHAVRY_DB_MAX_OVERFLOW=20

# OPA
BEHAVRY_OPA_URL=http://opa:8181
BEHAVRY_OPA_FAIL_CLOSED=true

# JWT keys (paste PEM, including header/footer lines)
BEHAVRY_JWT_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n..."
BEHAVRY_JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n..."

# Auth provider (password | clerk | oidc)
BEHAVRY_AUTH_PROVIDER=password

# CORS
BEHAVRY_CORS_ORIGINS_STR=https://app.your-domain.com

# Webhooks (optional)
BEHAVRY_WEBHOOK_URL=https://hooks.slack.com/services/...
BEHAVRY_WEBHOOK_SECRET=<signing-secret>
BEHAVRY_WEBHOOK_MIN_SEVERITY=high

# Data protection (optional — set if dp_mode=encrypted)
# BEHAVRY_LOCAL_ENCRYPTION_KEY=<base64-encoded-32-byte-key>

# Observability (optional)
# BEHAVRY_SENTRY_DSN=https://...@sentry.io/...
# BEHAVRY_METRICS_TOKEN=<random-bearer-token>

Complete `.env` for Data Plane

BEHAVRY_ENV=production
BEHAVRY_DEPLOYMENT_MODE=data-plane
BEHAVRY_CONTROL_PLANE_URL=https://control.behavry.com
BEHAVRY_DATA_PLANE_TOKEN=<token-from-control-plane>
BEHAVRY_LICENSE_KEY=<license-key>
BEHAVRY_DEPLOYMENT_ID=dp-us-east-1-01
BEHAVRY_HEARTBEAT_INTERVAL=60

# Database (local to data plane)
BEHAVRY_DB_URL=postgresql+asyncpg://behavry:<db-password>@db:5432/behavry

# OPA (bundle-polling mode — configured via opa-data-plane.yaml)
BEHAVRY_OPA_URL=http://opa:8181
BEHAVRY_OPA_FAIL_CLOSED=true

# JWT keys (synced from control plane JWKS, or set manually)
BEHAVRY_JWT_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n..."
BEHAVRY_JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n..."

Authentication Providers

Variable	Default	Required	Description
`BEHAVRY_CLERK_SECRET_KEY`	—	Clerk only	Clerk backend secret, used for org provisioning and webhook signature verification
`BEHAVRY_CLERK_WEBHOOK_SECRET`	—	Clerk only	Secret used to verify Clerk webhooks (user / org events)
`BEHAVRY_OIDC_ISSUER`	—	OIDC only	Issuer URL (e.g. `https://login.microsoftonline.com/{tenant}/v2.0`)
`BEHAVRY_OIDC_CLIENT_ID`	—	OIDC only	OIDC client ID
`BEHAVRY_OIDC_CLIENT_SECRET`	—	OIDC only	OIDC client secret
`BEHAVRY_SAML_IDP_METADATA_URL`	—	SAML only	IdP metadata URL (or upload via API)

The dashboard and docs sites also read a publishable key at build time:

Variable	Where	Description
`VITE_CLERK_PUBLISHABLE_KEY`	dashboard	Clerk publishable key used by the React dashboard
`CLERK_PUBLISHABLE_KEY`	docsite	Clerk publishable key used by the documentation site's auth gate

Both should point to the same Clerk project; add the dashboard and docs hostnames as Clerk satellite domains so sessions span both.

AI Surface Proxies

Behavry forwards LLM traffic to upstream providers through dedicated proxy modules. The upstream URL for each can be overridden (useful for self-hosted or on-prem model endpoints):

Variable	Default	Description
`BEHAVRY_NEMOCLAW_URL`	`http://localhost:7860`	NVIDIA NemoClaw API upstream
`BEHAVRY_OPENSHELL_URL`	`http://localhost:7861`	NVIDIA OpenShell API upstream

The Anthropic, OpenAI, Google Gemini, and Ollama proxies use the standard provider base URLs and pick up credentials at request time from the client.

Data Protection (Sprint DP)

Variable	Default	Description
`BEHAVRY_LOCAL_ENCRYPTION_KEY`	—	Base64-encoded 32-byte AES-256 key for the local KMS provider (dev only)
`BEHAVRY_KMS_PROVIDER`	`local`	`local` or `aws`
`BEHAVRY_AWS_KMS_KEY_ARN`	—	CMK ARN when `BEHAVRY_KMS_PROVIDER=aws`

See Data Protection Pipeline.

Core Settings​

Database​

OPA Policy Engine​

JWT / Auth​

Admin Auth​

Clerk OIDC (when BEHAVRY_AUTH_PROVIDER=clerk)​

Generic OIDC (when BEHAVRY_AUTH_PROVIDER=oidc)​

CORS​

SSE​

Webhooks / SIEM​

Demo / External Integrations​

Ollama Proxy​

Deployment Mode (Sprint W)​

Data Protection (Sprint DP)​

Observability (Sprint O)​

Complete Minimal .env for Local Dev​

Complete .env for Production (Standalone)​

Complete .env for Data Plane​

Authentication Providers​

AI Surface Proxies​

Data Protection (Sprint DP)​

Core Settings

Database

OPA Policy Engine

JWT / Auth

Admin Auth

Clerk OIDC (when `BEHAVRY_AUTH_PROVIDER=clerk`)

Generic OIDC (when `BEHAVRY_AUTH_PROVIDER=oidc`)

CORS

SSE

Webhooks / SIEM

Demo / External Integrations

Ollama Proxy

Deployment Mode (Sprint W)

Data Protection (Sprint DP)

Observability (Sprint O)

Complete Minimal `.env` for Local Dev

Complete `.env` for Production (Standalone)

Complete `.env` for Data Plane

Authentication Providers

AI Surface Proxies

Data Protection (Sprint DP)