The Problem
Enterprises that want a local‑only voice assistant often have to stitch together multiple services (LLM, STT/TTS, home‑automation, custom actions) and maintain separate deployment pipelines. The result is fragmented tooling, hard‑coded API keys, and a high barrier to adding new capabilities without writing code.
What This Does
VoiceAI (fork of CAAL) delivers a single Docker‑based stack that bundles:
LiveKit Agents for real‑time audio routing (livekit.yaml). Pluggable LLM/STT/TTS back‑ends – Ollama + Kokoro (GPU) or Groq + Piper (CPU‑only) – selected in the first‑start wizard (frontend/components/setup/setup-wizard.tsx). n8n workflow discovery that automatically exposes each workflow as a tool (frontend/app/api/tools/n8n-workflows/route.ts). Home‑Assistant integration via MCP tools (frontend/app/api/tools/registry/route.ts).
The UI lives in frontend/components/app/app.tsx and is served by Next.js (frontend/app/(app)/page.tsx). Mobile clients are provided by the Flutter project under mobile/.
How To Use It
Clone & prepare environment git clone https://github.com/CoreWorxLab/VoiceAI.git cd VoiceAI cp .env.example .env # edit CAALHOSTIP to your LAN address
The only required variable is CAALHOSTIP (documented in .env.example). Choose a deployment mode GPU‑enabled (local) docker compose up -d # uses docker-compose.yaml
CPU‑only (no GPU)
docker compose -f docker-compose.cpu.yaml up -d
The compose files reference the frontend Dockerfile (frontend/Dockerfile) and the LiveKit backend image defined in the root Dockerfile. Run the setup wizard Open a browser to http://<CAALHOSTIP>:3000. The wizard (frontend/components/setup/setup-wizard.tsx) guides you through: Selecting LLM provider (Ollama or Groq) Selecting TTS provider (Kokoro or Piper) Adding Home‑Assistant credentials Enabling n8n discovery (requires an accessible n8n instance) Verify API endpoints The backend exposes REST routes under frontend/app/api/…, e.g.: GET /api/tools/n8n-workflows – lists discovered workflows. POST /api/tools/install – installs a selected tool. POST /api/wake – triggers wake‑word processing. Optional: Mobile client Build the Flutter app (mobile/) with the standard Flutter toolchain (flutter build apk / flutter build ios). The app reads the same backend URLs configured via the wizard.
Real‑World Use
A smart‑office deployment could run the GPU stack on a dedicated Linux server. An n8n workflow that queries a corporate inventory system is automatically exposed as the tool inventorylookup. Users say “Hey Cal, what’s the status of laptop #123?” and the assistant calls the workflow, returns the JSON payload, and speaks the answer via the local TTS engine—all without writing custom code.
// Example call from a custom front‑end component await fetch('/api/tools/n8n-workflow/42', {method: 'POST', body: JSON.stringify({serial:'123'})});
Code Health & Issues
| Severity | Issue |
|---|---|
| Low | Missing explicit backend tests – only front‑end unit tests (frontend/lib/tests/workflow-sanitizer.test.ts) are present. |
| Low | Environment variable documentation limited – only CAALHOST_IP is shown in .env.example; other variables used by Dockerfiles (e.g., API keys) rely on runtime prompts. |
| Low | Potential race in tool reload – /api/tools/reload-tools may be called before n8n discovery finishes; no visible synchronization logic. |
| Low | Dependency hygiene – both package.json and pnpm-lock.yaml exist, but CI uses pnpm install (implied by frontend/.github/workflows/build-and-test.yaml). No automated vulnerability scan configured. |
| Low | License present – MIT, but no SPDX identifier in source files. |
| Low | CI coverage – GitHub Actions run lint, build, and tests, indicating a functional CI pipeline. |
Overall the repository shows a coherent structure, CI configuration, and a clear Docker‑first deployment model. The few gaps are typical for a rapidly evolving prototype.
The Bottom Line
VoiceAI provides a ready‑to‑run, Docker‑based local voice assistant that can be extended via n8n workflows and Home‑Assistant without writing code. It is well‑structured, documented, and includes CI, but the backend lacks dedicated tests and full env‑var documentation. Suitable for teams that need a self‑hosted voice interface and are comfortable managing Docker and optional GPU resources.