Skip to main content

Installation

ChatWalaʻau is distributed on PyPI and runs on Python 3.12+.

Windows desktop app

On Windows you can instead install ChatWalaʻau Desktop, which bundles its own Python and needs no command line. See Desktop app (Windows).

Quick start​

pip install chatwalaau
chatwalaau init
# Edit .env: choose a provider and how it authenticates (see below)
chatwalaau

Then open http://localhost:8000/chat.

ChatWalaʻau talks to Azure OpenAI and/or Anthropic (Claude) -- pick whichever you have access to. The fastest start is an API key (no Azure CLI, no tenant):

# Azure OpenAI with an API key
AZURE_OPENAI_ENDPOINT=https://<your-resource>.openai.azure.com/
AZURE_OPENAI_API_KEY=<your-key>
AZURE_OPENAI_MODELS=gpt-4o
# ...or Anthropic (Claude) with an API key, no Azure at all
ANTHROPIC_MODELS=claude-sonnet-4-5-20250929
ANTHROPIC_API_KEY=sk-ant-...

Prefer Microsoft Entra ID for Azure? Use the Azure CLI lane (az login), managed identity, or auto-discovery instead -- see Configuration -> Authentication.

CommandWhat it does
chatwalaau initGenerate a .env template (--force overwrites).
chatwalaauStart the server (the Azure CLI pre-check runs only on the cli credential lane).

Requirements​

  • Python 3.12+
  • A model provider -- Azure OpenAI or Anthropic Claude (or both) -- unless you run in demo mode
  • Only if you authenticate Azure with Entra ID via the cli lane: the Azure CLI (az login). API-key and managed-identity lanes need no CLI -- see Configuration -> Authentication.

Corporate networks (TLS-intercepting proxy)​

Behind a proxy that re-signs traffic with an in-house root CA (Zscaler, Netskope, on-prem middlebox), the first outbound HTTPS call can fail with CERTIFICATE_VERIFY_FAILED. Install the opt-in corp extras so Python trusts the OS certificate store:

pip install "chatwalaau[corp]"

This adds pip-system-certs; default installs are unaffected. Alternatively point Python at an explicit CA bundle:

export SSL_CERT_FILE=/path/to/corp-root-ca.pem
export REQUESTS_CA_BUNDLE=/path/to/corp-root-ca.pem

Upgrading​

pip install -U chatwalaau
chatwalaau env diff   # see which new settings your .env is missing

See Configuration -> Keeping .env current for env diff / env sync.

No going back from v0.197.0

Upgrading to v0.197.0 or later is one-way. Back up your data folders (.sessions/, .usage/) first if you may need to go back: once v0.197.0 has run, do not install an older version over it, and do not run an older and a newer version against the same folders at the same time. Your existing chats are not affected by the upgrade itself.

Fewer packages from v0.219.0

From v0.219.0, ChatWalaau installs only the Microsoft Agent Framework packages it uses (149 packages instead of 263). An upgrade does not remove the packages that are no longer needed; a fresh virtual environment is the cleanest way to get the smaller set. If your own code in the same environment imports one of the dropped packages (for example boto3 or google-genai), install it yourself.

Next steps​

  • Configuration -- required settings and credential lanes.
  • Features -- what you can do once it is running.