Skip to main content

Desktop app (Windows)

ChatWalaʻau Desktop is the same ChatWalaʻau you get from pip install, packaged as a Windows application. It carries its own Python runtime and dependencies, sets itself up on first launch, and opens the chat in its own window. Nothing else needs to be installed.

Requirements​

  • Windows 10 (22H2) or Windows 11, 64-bit (x64)
  • About 3 GB of free disk space for the first setup
  • A model provider (Azure OpenAI, Anthropic, OpenAI, or Microsoft Foundry) -- configured in the app, exactly as in the pip install
Windows on ARM (Snapdragon and other ARM devices)

Download the same installer. There is no separate ARM build: Windows runs the x64 app through its built-in emulation, so everything works, with a slower first launch and start. This has not yet been validated on ARM hardware by us -- if something looks wrong, send Help > Export Diagnostics... (it records that the app is running on an ARM device).

macOS and Linux users: use the pip installation for now.

Install​

  1. Download ChatWalaau-Setup-<version>.exe from the GitHub Releases page.
  2. Run it. The installer is per-user and needs no administrator rights. It installs to %LOCALAPPDATA%\Programs\ChatWalaau and adds Start-menu and desktop shortcuts.
Windows SmartScreen

Until release builds are code-signed, Windows may show "Windows protected your PC". Choose More info -> Run anyway only for an installer you downloaded from the official Releases page.

First launch​

The first start after installing (or after an update) prepares a private Python environment from the installer. This takes a few minutes, shows its progress, and needs no internet connection. Later starts take seconds.

When the chat opens with no model configured, open Model Settings and add one -- the same screens as in the browser version. API keys and endpoints go into the app's .env (Help -> Open Data Folder), as described in Configuration.

Where your data lives​

Everything the app stores stays in %LOCALAPPDATA%\ChatWalaau\desktop\profile: .env, settings, conversations, uploads, the RAG knowledge base, agents and skills. The workspace for coding tools defaults to profile\workspace.

Updates, Rebuild Environment, and uninstalling never delete this folder.

The app's .env​

The .env in the profile folder (Help -> Open Data Folder) is read when the app starts. Every value in it is available to the app, including ${VAR} references in the Model Offering Catalog (for example "endpoint": "${AZURE_OPENAI_ENDPOINT}"). After you edit .env, quit and restart the app. Only APP_HOST / APP_PORT are overridden by the app (see below).

Updates​

The app checks the Releases page at startup and every few hours.

  • Signed builds download the update in the background and install it when you choose Restart to Update, or the next time you quit.
  • Unsigned builds tell you a new version is available and open the download page; run the new installer over the old one. Your data is kept.

After an update the first start rebuilds the Python environment. If you (or the assistant) had installed extra Python packages, the app lists them and offers to install them again (this step needs internet).

You can check manually with Help -> Check for Updates.

Differences from the pip installation​

TopicDesktop app
AddressRuns on 127.0.0.1 with a port the app chooses; only the app's own window can use it. APP_HOST / APP_PORT in .env are ignored.
Closing the windowQuits the app. Cron jobs and pipeline jobs do not run while it is closed (you are asked before quitting when some are active).
Teams channel, inbound webhooksNot available (they need a public URL).
HTTPS/TLS settingsNot used.
External toolsGit, Node.js (npx) and the Azure CLI are not bundled. Install them yourself if your MCP servers or Entra ID sign-in need them.
Extra Python packagesPackages the assistant installs go into the app's own environment and are listed for reinstall after updates.

Troubleshooting​

  • The start screen shows an error -- choose Retry, or Open Logs and look at backend.log and environment.log.

  • Something is broken after an update -- Help -> Rebuild Environment recreates the Python environment offline and keeps all your data.

  • Reporting a problem -- Help -> Export Diagnostics saves a JSON file with versions, paths and checks (no .env contents, no conversations).

  • Azure sign-in error when you send a message -- a message like AADSTS50020: User account ... does not exist in tenant means the desktop app asked the Azure CLI for a token (the cli credential lane) and the account you are signed in with belongs to a different tenant than your Azure OpenAI resource. Either sign in to the right tenant in a terminal:

    az logout
    az login --tenant <your-tenant-id> --scope https://cognitiveservices.azure.com/.default

    and restart the app, or avoid the Azure CLI entirely by putting AZURE_OPENAI_API_KEY=<your-key> in the app's .env (Help -> Open Data Folder), which takes precedence over every Entra ID lane. The Azure CLI is not bundled with the desktop app; the cli lane needs it installed separately. See Authentication.

  • ${VAR} shows "not set" in the Model Offering Catalog, although the variable is in .env -- check the spelling of the name, then restart the app. Versions before 0.157.2 did not pass .env values to catalog references; update to 0.157.2 or later.

  • A scheduled job stays "Running", or a harness agent never answers, until the window is closed -- this was a defect in versions before 0.157.2 (it also affected shell tools and skill scripts). Update to 0.157.2 or later. A job that still shows "Running" after the update can be re-run from the Cron screen.

Uninstall​

Remove ChatWalaʻau in Windows Settings -> Apps. To remove your data as well, delete %LOCALAPPDATA%\ChatWalaau afterwards.

Building from source​

Developers can build the installer from the repository's desktop/ folder; see desktop/README.md on GitHub.