chatwalaau

ChatWalaʻau

A local-first AI agent runtime — chat, tools, RAG, and MCP in one pip install.

Run an AI agent workspace on localhost. Chat with models from multiple providers, work with files and documents, connect tools, and build agents and workflows — all from one app.

The UI, runtime, and local storage run on your machine. Model requests go to your configured providers.

Built in Hawaiʻi, powered by Microsoft Agent Framework.

Documentation · Installation · Configuration

Quick Start

On Windows and prefer an app? Install ChatWalaʻau Desktop from the Releases page -- it bundles its own Python, so nothing else is needed. The same x64 installer also runs on Windows on ARM devices through emulation. Everything in the app's own .env -- including ${VAR} references in the model catalog -- applies on start, and scheduled jobs, harness agents and shell tools run while the window is open. See Desktop app.

1. Install and initialize

pip install chatwalaau
chatwalaau init

The setup creates your .env file and offers a guided first-model configuration.

2. Configure credentials and a model

Add your provider credentials to .env. For example, with Azure OpenAI:

AZURE_OPENAI_ENDPOINT=https://<your-resource>.openai.azure.com/
AZURE_OPENAI_API_KEY=<your-key>

Configure at least one chat model through the setup wizard or:

chatwalaau models add

Models are stored in model_offerings.jsonc. You can also manage chat, image, embedding, and helper-model assignments in App Settings.

Supported providers: Azure OpenAI · Anthropic · OpenAI · Microsoft Foundry

See Models & Reasoning for provider-specific setup.

3. Start chatting

chatwalaau

Open localhost:8000/chat.

Using Entra ID instead of an Azure API key? See the Authentication guide.

Behind a corporate TLS proxy? Install with pip install "chatwalaau[corp]".

pip install --upgrade chatwalaau
chatwalaau settings migrate --write

Runtime settings previously stored in .env now belong in app_settings.jsonc, editable through App Settings. Credentials, endpoints, bootstrap paths, and feature enable-gates remain in .env.

Upgrading to 0.197.0 or later is one-way. Back up your data folder (.sessions/, .usage/, or the Desktop data folder) first: an earlier version must not be installed over it afterwards.

Legacy model environment variables are no longer supported. Configure models in model_offerings.jsonc using chatwalaau models add or App Settings.

See the Configuration guide before migrating.

Highlights

Area	What you can do
Chat & media	Render Markdown, code, math, and Mermaid diagrams. Use voice (including real-time Live conversation), image analysis, PDF attachments, web search with citations, and a built-in paint canvas.
Conversation controls	Use slash commands, search and bookmark chats, navigate messages, start temporary chats, and mask your content with Privacy Screen for screen sharing. Continue chatting from a phone: the chat and chat list adapt to small screens, with a drawer chat list and touch-friendly controls.
AI discussion	Let several AI participants (proposer, critic, implementer, or your own agents) discuss a topic for a few rounds while you lead: a moderator organizes the points, the discussion waits for you after each step, and you make the decision. Bounded by a token budget; the participants have no tools.
Models	Azure OpenAI, OpenAI, Microsoft Foundry, and Claude (direct or on Foundry), all configured in one model catalog. Availability depends on the model and deployment.
Tools & Skills	Use image, weather, and coding tools, typed decisions with probabilities (Microsoft-Decision-1), prompt templates, and catalog-installed Agent Skills with license/update tracking. Choose which tools each agent has; enabled tools run without an approval step.
CodeAct compute sandbox	Let every agent run a short Python snippet in an isolated sandbox for exact arithmetic, dates, unit conversion, data aggregation, JSON reshaping, and regular expressions.
Computer Use (Windows)	Let an agent see and operate desktop applications on your own Windows machine: one batch of clicks and keystrokes per decision, waits for the screen to settle instead of sleeping, drags-and-drops and draws, marks the window it controls with a glow, and stops on Ctrl+Alt+End or when you move the mouse. Watch what it sees in a live capture view, with every screenshot kept for review. Works in chat, in harness agents, and in Live conversations, with Azure OpenAI, OpenAI, and Claude models; off until you enable it.
Knowledge & RAG	Ingest PDFs into a ChromaDB-backed knowledge base. Submit, monitor, and cancel ingestion through Pipeline Jobs.
Ontology	Build RDF concept models, including named graphs, on a visual canvas. Import and export all major RDF formats, annotate statements, and query with SPARQL or natural language, optionally with RDFS or OWL 2 RL inference (computed after each save, with explanations). Agents can use your ontologies too. Values are kept exactly as written and checked against the W3C RDF 1.1/1.2 test suites. Version history with restore, an editable Data view with CSV table import (rows checked against SHACL shapes before they are added), one-click Checks and SHACL validation are built in, and ontologies can import each other from your catalog.
MCP	Connect MCP servers using Claude Desktop-compatible configuration. Toggle servers and tools, reload connections, and render interactive MCP Apps in chat.
Memory	Maintain agent identity, user preferences, and project knowledge in editable Markdown files with automatic backups.
Workspace	Browse and edit files in a Monaco-based editor with tabs and split panes. Upload folders, download ZIPs, preview PDFs and images, and attach them to chat. Download or open files the assistant creates straight from its answer.
Agents & workflows	Define agents in YAML or a GUI. Compose workflows in a visual DAG editor with branching, loops, tool calls, human input, and live execution views. Run in chat or as background jobs. Workflow HTTP calls are opt-in, limited to allowed hosts, and size-capped.
Harness agents	Run autonomous coding agents on Azure OpenAI, Foundry, or Claude models with planning (plan approval optional), todo lists with a live task indicator, session memory, workspace-scoped file and shell access (including line-range reads), Skills, and context compaction whose summaries remember the steps already taken -- uninterrupted by approval prompts.
Automation & Teams	Schedule workspace scripts, chat with agents in Microsoft Teams, and summarize meeting transcripts through Microsoft Graph webhooks or on demand.
API & usage	Connect OpenAI-SDK applications through /v1/responses. See token usage on a built-in dashboard, by day, month, type, model, or chat, in your own time zone. Break down input, cache reads, cache writes, output, and reasoning, and export the raw records as CSV for BI. Each model call is counted once, even across multi-step tool turns. Token counts are not billing totals.
Settings & diagnostics	Manage models and runtime settings in the app, with clear notices about when changes take effect. Inspect prompts and tool availability with opt-in Prompt Dump.
Local-first storage & access	Keep sessions, vectors, and uploads on your machine. Chat history is saved through one locked write path, so a brief file conflict never wipes a conversation, and branched chats keep their title, folder, and own copies of images. Use API-key authentication, optional web sign-in, session-protected images, and restart-persistent sign-in.

Some features require explicit enablement or additional provider configuration. See the feature documentation for setup and limitations.

UI Preview

Documentation

Full guides are available in English and 日本語, with full-text search.

• Get started: Installation · Desktop app (Windows) · Configuration · Authentication
• Use the app: Chat & UI · Voice & Live conversation · Models & Reasoning · Memory & Sessions · AI Discussion
• Build agents: Tools & Skills · Knowledge & MCP · Declarative Agents · Computer Use · CodeAct
• Integrate: OpenAI-compatible API · CLI · Usage Statistics · Token Usage Dashboard
• Develop & deploy: Development Setup · Networking & Operations

Development

The backend uses Python + uv; the frontend uses pnpm.

For prerequisites, local development commands, and production builds, see the Development Setup guide.

Supported Platforms

Windows 10/11 · macOS (Intel / Apple Silicon) · Linux

About the Name

Walaʻau means “to chat, talk, or converse” in Hawaiian. Built in Hawaiʻi, this project uses the name with respect and gratitude for the Hawaiian language and its community.

License

Apache-2.0