CAAL

Self-hosted voice assistant you actually own. Secure by design - the LLM never sees your API keys.

CAAL is an open-source voice assistant built on LiveKit Agents that runs entirely on your hardware. Your voice, your data, your credentials — all on your network.

---

Why CAAL?

Secure by architecture. The model never sees your API keys. Ever. Credentials live in n8n's encrypted credential store. The LLM sends parameters to a webhook, the workflow handles auth. Even if a prompt injection succeeds, the model can only call pre-built workflows — no shell access, no curl, no ability to transmit data. It's an air gap for the LLM. Every tool in the registry goes through automated security review and human approval before it's available to install.

Purpose-built model. CAAL ships with caal-ministral — a fine-tuned 8B model trained specifically for voice tool calling. It knows how to control your smart home, chain tools together, and respond naturally. The LLM is one piece of the architecture, not the architecture. It handles decisions that code can't — which tool to call, what parameters to use, when to chain steps. Everything else is code. That's why an 8B model works.

ollama pull coreworxlab/caal-ministral:latest

Infinitely extensible. Any n8n workflow becomes a voice-activated tool. Control Home Assistant devices, query APIs, automate your life — then share your tools with the community via the CAAL Tool Registry. Tools follow a suite convention — fewer tools, better accuracy, more reliable routing.

Local by default. Runs fully on your network with Ollama. No accounts, no telemetry, no cloud dependency. Want to use Groq, OpenRouter, or any OpenAI-compatible API? Your choice. Your credentials and tool executions never leave your network regardless.

---

Features

• Tool Registry — Browse and install community tools with one click. Every submission goes through automated security review and human approval
• Tool Chaining — Sequential multi-tool calls in one prompt. The model uses real data from each step to inform the next
• Home Assistant — Voice control across lights, covers, locks, climate, media, and more via hass
• n8n Workflows — Any workflow becomes a tool. Visual, inspectable, shareable, auditable through n8n's execution history
• Flexible Providers — Ollama, Groq, OpenRouter, or any OpenAI-compatible API. Speaches or Groq for STT. Kokoro or Piper for TTS
• Short-Term Memory — Store and recall information across sessions
• Internationalization — English, French, Italian, with more coming
• Wake Word — "Hey Cal" via OpenWakeWord
• Web Search — DuckDuckGo integration for real-time information
• Mobile App — Android client available from Releases
• Webhook API — REST API for announcements, settings, and external triggers

---

Quick Start

git clone https://github.com/CoreWorxLab/caal.git
cd caal
cp .env.example .env
nano .env  # Set CAAL_HOST_IP to your server's LAN IP

# If using Ollama (recommended)
ollama pull coreworxlab/caal-ministral:latest

docker compose up -d

Open https://YOUR_SERVER_IP:3443 and complete the setup wizard.

Requires Docker with NVIDIA Container Toolkit and 8GB+ VRAM. For CPU-only or Apple Silicon setups, see Deployment Options.

Deployment Options

Mode	Hardware	Command	Guide
GPU	Linux + NVIDIA GPU	docker compose up -d	Quick Start above
CPU-only	Any Docker host	docker compose -f docker-compose.cpu.yaml up -d	Wiki: CPU Mode
Apple Silicon	M1/M2/M3/M4 Mac	./start-apple.sh	Apple Silicon Guide
Distributed	GPU server + frontend	See guide	Distributed Guide

HTTPS & Network

HTTPS is enabled by default with auto-generated self-signed certificates. This is required because browsers block microphone access on non-localhost HTTP.

To avoid the browser certificate warning, trust the auto-generated cert:

./trust-cert.sh

This works on macOS and Linux (Debian/Ubuntu, RHEL/Fedora, Arch, Chrome, Firefox). Pass --yes to skip the confirmation prompt. On Apple Silicon, start-apple.sh runs it automatically.

Alternatively, for browser-trusted certs use mkcert:

mkcert -install && mkcert 192.168.1.100
mkdir -p certs && mv 192.168.1.100.pem certs/server.crt && mv 192.168.1.100-key.pem certs/server.key

For remote access via Tailscale, set HTTPS_DOMAIN in .env to your Tailscale domain. See the wiki for details.

The mobile app connects via LiveKit directly and doesn't require HTTPS.

---

Documentation

Resource	Description
Wiki	Full documentation — architecture, configuration, deployment
Home Assistant	Smart home integration setup and usage
n8n Workflows	Creating and connecting workflow tools
Apple Silicon	Running on M1/M2/M3/M4 Macs
Distributed Deployment	Split GPU backend and frontend
Internationalization	Adding language support
Tool Registry	Browse and submit community tools
CONTRIBUTING.md	Development setup and contribution guidelines

---

Architecture

                          https://<IP>:3443    https://<IP>:7443
                                │                     │
                          ┌─────┴─────────────────────┴─────┐
                          │           nginx (TLS)           │
                          │         :3443  :7443            │
                          └─────┬─────────────────┬─────────┘
                                │                 │
┌───────────────────────────────┼─────────────────┼───────────────────┐
│  Docker Compose Stack         │                 │                   │
│                               │                 │                   │
│  ┌────────────┐         ┌─────┴──────┐  ┌───────┴────┐  ┌────────┐  │
│  │  Speaches  │         │  Frontend  │  │  LiveKit   │  │ Kokoro │  │
│  │(STT, GPU)  │         │  (Next.js) │  │   Server   │  │ (TTS)  │  │
│  │   :8000    │         │   :3000    │  │   :7880    │  │ :8880  │  │
│  └─────┬──────┘         └─────┬──────┘  └─────┬──────┘  └───┬────┘  │
│        │                      │               │             │       │
│        └──────────────────────┼───────────────┼─────────────┘       │
│                               │               │                     │
│                         ┌─────┴───────────────┴─────┐               │
│                         │         Agent             │               │
│                         │    (Voice Pipeline)       │               │
│                         │    :8889 (webhooks)       │               │
│                         └─────────┬─────────────────┘               │
│                                   │                                 │
└───────────────────────────────────┼─────────────────────────────────┘
                                    │
           ┌────────────────────────┼────────────────────────┐
           │                        │                        │
     ┌─────┴─────┐           ┌──────┴──────┐          ┌──────┴──────┐
     │   Ollama  │           │     n8n     │          │    Home     │
     │Groq / OR  │           │  Workflows  │          │  Assistant  │
     └───────────┘           └─────────────┘          └─────────────┘
                      External Services (via MCP)

---

Community

CAAL is built in the open. If you build a tool, we see the PR. If you find a bug, we see the issue.

• Tool Registry — Browse, install, and share tools
• Discussions — Feature requests, questions, feedback
• Fine-tuned Model — ollama pull coreworxlab/caal-ministral

---

Related Projects

• LiveKit Agents - Voice agent framework
• Speaches - Faster-Whisper STT + Piper TTS
• Kokoro-FastAPI - Kokoro TTS server
• Ollama - Local LLM server
• Groq - Fast cloud LLM inference
• OpenRouter - Unified API for 200+ models
• n8n - Workflow automation
• Home Assistant - Smart home platform

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

MIT License — see LICENSE for details.