Skip to main content

Configuration

ChatWalaʻau is configured through a .env file. Run chatwalaau init to generate a template, edit the values, and restart.

Required settings​

At minimum, point the runtime at an Azure OpenAI endpoint and a model:

AZURE_OPENAI_ENDPOINT=https://<your-resource>.openai.azure.com/
AZURE_OPENAI_MODELS=gpt-4o

AZURE_OPENAI_MODELS is a comma-separated list; the first entry is the default model. See Models & Reasoning for multi-model and Anthropic configuration.

Azure authentication​

The backend resolves Azure OpenAI credentials through four lanes, selected by two variables. Pick the one that matches where you run.

LaneWhen to use.env setting
api-keyFirst run / PoC / CI / container; cross-tenantAZURE_OPENAI_API_KEY=<key>
cli (default)Localhost dev with az loginAZURE_CREDENTIAL_MODE=cli (or unset)
managed-identityAzure App Service, Container Apps, AKS, Functions, VMAZURE_CREDENTIAL_MODE=managed-identity
defaultOne image across many surfacesAZURE_CREDENTIAL_MODE=default

Precedence: AZURE_OPENAI_API_KEY always wins over AZURE_CREDENTIAL_MODE. One INFO log line per process announces the active lane on first credential resolution; the key value is never logged.

Cloud deployments

For managed-identity, assign a Managed Identity to the compute and grant it the Cognitive Services OpenAI User role on the Azure OpenAI resource. User-assigned identities also need AZURE_CLIENT_ID. AKS workloads using federated identity should use AZURE_CREDENTIAL_MODE=default so the SDK's WorkloadIdentityCredential is picked up. The chatwalaau CLI skips its az account show precheck whenever the active lane is not cli.

How the .env is organized​

The template groups settings by feature. Most features are opt-in and default off, so the server works after install with only the required Azure settings. Each feature page in this documentation lists the variables it uses; this page is the entry point, not an exhaustive table.

Keeping .env current across releases​

New releases usually add value through new opt-in settings, so the server keeps working after pip install -U -- but you cannot tell from your own .env which settings became available, and old keys pile up. Two offline commands reconcile your .env against the template bundled with the installed release:

chatwalaau env diff           # settings added / removed since your .env was made
chatwalaau env diff --json    # machine-readable

chatwalaau env sync           # preview the reconciliation (dry-run)
chatwalaau env sync --write   # apply, after writing a timestamped backup
  • Your values are preserved verbatim -- only layout and per-key comments are refreshed to the installed release.
  • Nothing is deleted -- keys the template no longer has move to an Unmanaged keys section.
  • A timestamped backup (.env.<UTC>.bak) is written before --write.

On startup, the server logs one line when your .env is missing newly added keys.

Next steps​