|
|
||
|---|---|---|
| .github | ||
| docs | ||
| frontend | ||
| integrations/openwebui | ||
| mobile | ||
| models | ||
| prompt | ||
| src/caal | ||
| .dockerignore | ||
| .env.example | ||
| .gitattributes | ||
| .gitignore | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.md | ||
| docker-compose.apple.yaml | ||
| docker-compose.cpu.yaml | ||
| docker-compose.dev.yml | ||
| docker-compose.distributed.yml | ||
| docker-compose.yaml | ||
| Dockerfile | ||
| entrypoint.sh | ||
| LICENSE | ||
| livekit-tailscale.yaml | ||
| livekit-tailscale.yaml.template | ||
| livekit.yaml | ||
| mcp_servers.default.json | ||
| mcp_servers.json.example | ||
| nginx-distributed.conf | ||
| nginx.conf | ||
| pyproject.toml | ||
| README.md | ||
| SECURITY.md | ||
| settings.default.json | ||
| start-apple.sh | ||
| trust-cert.sh | ||
| uv.lock | ||
| voice_agent.py | ||
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.