Skip to content

Installation

Install uv

Schakel uses uv for dependency management. Install it if you don't have it:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with Homebrew
brew install uv

Clone and Install

git clone https://github.com/ragnarok22/schakel.git
cd schakel
uv sync

This installs all runtime dependencies into a virtual environment managed by uv.

Set Up Ollama

If you plan to use local LLMs (the default), install and start Ollama:

# Install Ollama (macOS)
brew install ollama

# Start the Ollama server
ollama serve

# Pull the default model
ollama pull llama3:8b

Model selection

llama3:8b is the default for all agents. You can use different models per agent in config.yaml -- for example, a smaller model for the intent router (fast classification) and a larger one for the general agent (better conversation quality).

Download a Piper Voice

Schakel uses Piper for text-to-speech. Download a voice model:

mkdir -p models/piper
cd models/piper

# Download the Spanish voice (default)
wget https://huggingface.co/rhasspy/piper-voices/resolve/main/es/es_ES/davefx/medium/es_ES-davefx-medium.onnx
wget https://huggingface.co/rhasspy/piper-voices/resolve/main/es/es_ES/davefx/medium/es_ES-davefx-medium.onnx.json

cd ../..

Update the audio.tts_voice path in config.yaml to point to the downloaded .onnx file.

Other languages

Piper supports many languages. Browse available voices at rhasspy/piper-voices on HuggingFace.

Create the Configuration

cp config.yaml.example config.yaml

At minimum, fill in your Home Assistant URL and long-lived access token. See the Configuration page for a full walkthrough of all options.

Verify the Setup

# Run lint + tests to verify everything is working
make check

This runs the linter (ruff) and the full test suite (56 test cases).

Start the Server

make dev

The server starts at http://localhost:8000. Connect a voice satellite to the WebSocket endpoint at ws://localhost:8000/ws/audio.

Spotify Setup (Optional)

If you want music control via Spotify:

  1. Create an app at developer.spotify.com/dashboard and note the client ID and secret.
  2. Add http://localhost:8888/callback as a redirect URI in the Spotify app settings.
  3. Fill in the spotify section of config.yaml.
  4. Run the one-time OAuth flow to cache your token:
uv run python -m app.services.music.spotify

This opens a browser for Spotify authorization and caches the token locally. You only need to do this once.

Without Spotify

If Spotify is not configured, the music agent gracefully responds with "La musica no esta disponible todavia." instead of crashing.