Configuration

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

Required settings

ChatWalaʻau needs at least one chat provider -- Azure OpenAI, Anthropic (Claude), OpenAI, Microsoft Foundry, or any combination. Configure whichever you have access to; you only need one to start. Models from every configured provider appear in the same selector and can be switched per turn.

Changed in v0.107.0

Chat models are configured exclusively through the Model Offering Catalog (model_offerings.jsonc). The legacy per-provider model variables (AZURE_OPENAI_MODELS, ANTHROPIC_MODELS, OPENAI_MODELS, FOUNDRY_MODELS, MODEL_MAX_CONTEXT_TOKENS, ANTHROPIC_HOSTING, and the per-provider chat endpoint/key variables) have been removed. Run chatwalaau init (first-model wizard), chatwalaau models add, or the in-app Model Settings screen.

Set your provider credentials in .env (shared with image, RAG, and speech):

AZURE_OPENAI_ENDPOINT=https://<your-resource>.openai.azure.com/
AZURE_OPENAI_API_KEY=<your-key>       # OR authenticate with Entra ID (see Authentication)
# ANTHROPIC_API_KEY / OPENAI_API_KEY as needed -- referenced by NAME from the catalog

Then author at least one chat offering in model_offerings.jsonc. Each offering self-describes its provider (azure-openai / anthropic / openai / foundry), model_ref (the real model/deployment name), optional endpoint / base_url / hosting / context_window, and an api_key_env (the NAME of the env var holding its key). One endpoint can front several model families, and direct + Foundry-hosted Claude coexist via per-offering hosting:

{
  "offerings": [
    { "id": "gpt-5.5", "provider": "azure-openai", "model_ref": "gpt-5.5",
      "endpoint": "${AZURE_OPENAI_ENDPOINT}", "default": true, "context_window": 1050000 },
    { "id": "claude", "provider": "anthropic", "hosting": "direct",
      "model_ref": "claude-sonnet-4-5-20250929", "api_key_env": "ANTHROPIC_API_KEY" },
    { "id": "gpt-5.1", "provider": "openai", "model_ref": "gpt-5.1", "api_key_env": "OPENAI_API_KEY" },
    { "id": "deepseek", "provider": "foundry", "model_ref": "deepseek-v4-pro",
      "endpoint": "https://<resource>.services.ai.azure.com/api/projects/<project>" }
  ]
}

An azure-openai offering may omit endpoint/api_key_env to reuse the shared AZURE_OPENAI_ENDPOINT + Azure credential lanes. A non-demo deployment with no chat offering still boots (with a startup warning, so the Model Settings screen stays reachable); chat is unavailable and returns a message pointing at the fix when you try it.

You do not have to hand-edit that file: set up your first model as an optional step of chatwalaau init (skip it with --no-model) or any time with chatwalaau models add, and manage the catalog going forward from the Model Settings screen in the chat sidebar -- saves apply immediately via hot reload, no restart.

See Models & Reasoning for multi-model switching, the Model Offering Catalog, Anthropic foundry hosting, the OpenAI and Microsoft Foundry providers, and per-message options.

Authentication

You choose how the runtime proves its identity to each provider. An API key is the simplest path where available and needs no Azure CLI or tenant; Microsoft Entra ID lanes are available for Azure OpenAI, for Anthropic on Foundry, and for Microsoft Foundry (which is Entra-only).

Azure OpenAI

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

Lane	When to use	.env setting
api-key	First run / PoC / CI / container; cross-tenant	AZURE_OPENAI_API_KEY=<key>
cli (default)	Localhost dev with az login (Entra ID)	AZURE_CREDENTIAL_MODE=cli (or unset)
managed-identity	Azure App Service, Container Apps, AKS, Functions, VM (Entra ID)	AZURE_CREDENTIAL_MODE=managed-identity
default	One image across many surfaces (Entra ID auto-discovery)	AZURE_CREDENTIAL_MODE=default

Precedence: AZURE_OPENAI_API_KEY always wins over AZURE_CREDENTIAL_MODE. So if you set an API key you do not need az login. 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.

Anthropic (Claude)

Anthropic has two hostings (ANTHROPIC_HOSTING=direct, the default, or foundry), each with its own auth:

Hosting	Auth	.env
direct (Anthropic public API)	API key	ANTHROPIC_API_KEY=sk-ant-...
foundry (Anthropic on Azure AI Foundry)	API key	ANTHROPIC_FOUNDRY_API_KEY=<key>
foundry	Microsoft Entra ID	leave ANTHROPIC_FOUNDRY_API_KEY empty; reuse AZURE_CREDENTIAL_MODE + AZURE_TENANT_ID

Foundry endpoint variables and caveats are in Models & Reasoning -> Anthropic provider.

OpenAI (direct)

The OpenAI public API authenticates by API key only -- there is no Entra ID lane.

Auth	.env
API key	OPENAI_API_KEY=sk-... (optional OPENAI_BASE_URL for OpenAI-compatible gateways)

Details are in Models & Reasoning -> OpenAI provider.

Microsoft Foundry

Foundry project endpoints authenticate with Entra ID only -- there is no API-key lane. The provider reuses the Azure OpenAI Entra lanes (AZURE_CREDENTIAL_MODE + AZURE_TENANT_ID); AZURE_OPENAI_API_KEY does not apply.

Auth	.env
Microsoft Entra ID	FOUNDRY_PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>; reuse AZURE_CREDENTIAL_MODE + AZURE_TENANT_ID

Grant the signed-in identity a Foundry data-plane role (for example Azure AI User) on the project. Details are in Models & Reasoning -> Microsoft Foundry provider.

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

• Features -- configure individual capabilities.
• Deployment & Ops -- run from source, build, and deploy.