Local voice assistant with n8n workflow integrations and Home Assistant control

Built on LiveKit Agents. Runs fully local with Ollama + Speaches + Kokoro, or GPU-free with Groq + Piper.

• First-Start Wizard - Configure everything from the browser, only one edit in .env required
• Flexible Providers - Ollama (local) or Groq (cloud) for LLM/STT, Kokoro or Piper for TTS
• Home Assistant - Native MCP integration with simplified hass_control and hass_get_state tools
• n8n Workflows - Expandable LLM tool capability - any n8n workflow can become a tool for CAAL
• Wake Word Detection - "Hey Cal" activation via OpenWakeWord (server-side)
• Web Search - DuckDuckGo integration for real-time information
• Webhook API - External triggers for announcements and tool reload
• Mobile App - Flutter client for Android and iOS

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

# GPU mode (Ollama + Kokoro)
docker compose up -d

# CPU-only mode (Groq + Piper) - no GPU required
docker compose -f docker-compose.cpu.yaml up -d

Open http://YOUR_SERVER_IP:3000 and complete the setup wizard.

Full local stack with GPU-accelerated STT (Speaches), LLM (Ollama) and TTS (Kokoro).

• Docker with NVIDIA Container Toolkit
• 12GB+ VRAM recommended

git clone https://github.com/CoreWorxLab/caal.git
cd caal
cp .env.example .env
nano .env  # Set CAAL_HOST_IP

docker compose up -d

The setup wizard will guide you through LLM (Ollama), TTS, and integration configuration.

Run CAAL without a GPU using Groq for LLM/STT and Piper (CPU) for TTS.

docker compose -f docker-compose.cpu.yaml up -d

For HTTPS:

docker compose -f docker-compose.cpu.yaml --profile https up -d

In the setup wizard:

1. Select Groq as LLM provider and enter your free API key
2. Select Piper as TTS provider (models download automatically)

Note: Voice data is sent to Groq's API. For fully local operation, use GPU mode with Ollama.

CAAL runs on Apple Silicon Macs using mlx-audio for Metal-accelerated STT/TTS.

./start-apple.sh

See docs/APPLE-SILICON.md for full setup instructions.

Run the GPU-intensive backend on a Linux server while using the frontend on a Mac or another device.

See docs/DISTRIBUTED-DEPLOYMENT.md for full setup instructions.

CAAL supports three network configurations:

Why? Browsers block microphone access on HTTP except from localhost. HTTPS is required for voice from other devices.

Note: For utilization with mobile app as the client, only LAN HTTP is required, not HTTPS

CAAL_HOST_IP=192.168.1.100  # Set in .env
docker compose up -d

Self-signed certificates are auto-generated if none exist in ./certs/.

# Configure .env
CAAL_HOST_IP=192.168.1.100
HTTPS_DOMAIN=192.168.1.100

# Start with HTTPS profile (certs auto-generated)
docker compose --profile https up -d

Access: https://192.168.1.100:3443

Trusted certs: For browser-trusted certs without warnings, 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

# Generate Tailscale certs
tailscale cert your-machine.tailnet.ts.net
mkdir -p certs && mv your-machine.tailnet.ts.net.crt certs/server.crt && mv your-machine.tailnet.ts.net.key certs/server.key

# Configure .env
CAAL_HOST_IP=100.x.x.x                         # tailscale ip -4
HTTPS_DOMAIN=your-machine.tailnet.ts.net

# Start
docker compose --profile https up -d

Access: https://your-machine.tailnet.ts.net:3443

Only CAAL_HOST_IP is required. Everything else is configured via the web UI.

See .env.example for additional options (ports, default models).

After setup, click the gear icon to access the settings panel:

• Agent - Agent name, voice selection, wake greetings
• Prompt - Default or custom system prompt
• Providers - LLM provider (Ollama/Groq), TTS provider (Kokoro/Piper)
• LLM Settings - Temperature, context size, max turns, turn detection settings
• Integrations - Home Assistant and n8n connection configuration
• Wake Word - Enable/disable, model selection, threshold, timeout

Control your smart home with voice commands. CAAL exposes two simplified tools:

• hass_control(action, target, value) - Control devices
  • Actions: turn_on, turn_off, set_volume, volume_up, volume_down, mute, unmute, pause, play, next, previous
  • Value: 0-100 for set_volume
• hass_get_state(target) - Query device states

Setup:

1. Create a Long-Lived Access Token in Home Assistant
2. In CAAL settings, enable Home Assistant and enter your host URL and token
3. Restart the agent - CAAL auto-discovers your devices

See docs/HOME-ASSISTANT.md for action mappings and examples.

Extend CAAL with any API, database, or service via n8n workflows exposed through MCP.

Setup n8n:

1. Enable MCP: Settings > MCP Access > Enable MCP
2. Set connection method to Access Token and copy the token
3. In CAAL settings, enable n8n and enter your MCP URL and token

Import example workflows:

cd n8n-workflows
cp config.env.example config.env
nano config.env  # Set your n8n IP and API key
python setup.py  # Creates all workflows

See docs/N8N-WORKFLOWS.md for how to create your own workflows.

Enable "Hey Cal" wake word in the settings panel. Two options:

• OpenWakeWord (Server-side) - Runs on the server, works with any client
• Picovoice (Client-side) - Requires access key and trained model per device

The agent exposes a REST API on port 8889 for external integrations.

Core Endpoints:

Settings & Configuration:

Wake Word:

curl -X POST http://localhost:8889/announce \
  -H "Content-Type: application/json" \
  -d '{"message": "Package delivered"}'

Android app available from GitHub Releases. Download the APK and install on your device.

Building from source:

cd mobile
flutter pub get
flutter build apk

See mobile/README.md for full documentation.

# Install dependencies
uv sync

# Start infrastructure
docker compose up -d livekit speaches kokoro

# Run agent locally
uv run voice_agent.py dev

# Run frontend locally
cd frontend && pnpm install && pnpm dev

Commands:

uv run ruff check src/   # Lint
uv run mypy src/         # Type check
uv run pytest            # Test

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

1. Check CAAL_HOST_IP matches your network mode
2. Verify firewall ports: 3000, 7880, 7881, 50000-50100 (UDP)
3. Check logs: docker compose logs livekit | grep -i "ice\|error"

# Ensure Ollama binds to network
OLLAMA_HOST=0.0.0.0 ollama serve

# From Docker, use host.docker.internal
OLLAMA_HOST=http://host.docker.internal:11434

Normal - models download on first run (~2-5 minutes):

docker compose logs -f speaches kokoro

If Home Assistant or n8n fail to connect, you'll see a toast notification with the error. Check:

• Host URL is reachable from the Docker container
• Access token is valid and has correct permissions
• For n8n: MCP Access is enabled in Settings

• LiveKit Agents - Voice agent framework
• Speaches - Faster-Whisper STT server (also includes Piper TTS)
• Kokoro-FastAPI - Kokoro TTS server
• Piper - Fast local TTS (CPU-friendly)
• mlx-audio - STT/TTS for Apple Silicon
• Ollama - Local LLM server
• Groq - Fast cloud LLM inference (free tier available)
• n8n - Workflow automation
• Home Assistant - Smart home platform

We welcome contributions! See CONTRIBUTING.md for guidelines.

MIT License - see LICENSE for details.