Development Setup

Run ChatWalaʻau from source for development.

Prerequisites

Tool	Version	Install
Node.js	20.19+ / 22.12+	nodejs.org
pnpm	10+	npm install -g pnpm
Python	3.12+	python.org
uv	0.9+	docs.astral.sh/uv
Azure CLI	2.x	Install Azure CLI

1. Backend

Windows (PowerShell):

cd backend
uv sync --prerelease=allow
uv run chatwalaau init --no-model     # writes .env from the bundled template
notepad .env          # set your Azure OpenAI endpoint

macOS / Linux:

cd backend
uv sync --prerelease=allow
uv run chatwalaau init --no-model     # writes .env from the bundled template
nano .env             # set your Azure OpenAI endpoint

chatwalaau init renders .env from backend/src/app/templates/.env.template, which is the single source of truth for the environment layout. (A mirrored backend/.env.sample existed before v0.130.0 and was removed -- a second hand-maintained copy only ever drifted from the template it copied.)

Required .env:

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

See Configuration -> Authentication for the Azure OpenAI credential lanes and Anthropic auth.

2. Frontend

cd frontend
pnpm install

3. Start the dev servers

Open two terminals:

# Terminal 1 -- backend at http://localhost:8000
cd backend
uv run uvicorn app.main:app --reload --app-dir src

# Terminal 2 -- frontend at http://localhost:5173 (API proxied to the backend)
cd frontend
pnpm dev

4. Production build

cd frontend
pnpm build

cd ../backend
uv run uvicorn app.main:app --app-dir src

The backend serves both the frontend build and the API at http://localhost:8000.

Tech stack

Layer	Technology	Purpose
Frontend	React 19 + TypeScript + Vite	UI framework
Frontend	Tailwind CSS + shadcn/ui	Styling + components
Frontend	Biome	Format + lint
Backend	FastAPI + Python 3.12+	API server
Backend	Microsoft Agent Framework	Agent execution + tool control
Backend	Ruff	Format + lint
Package	uv	Python dependencies
Package	pnpm	Node.js dependencies