Configuration¶

Schakel reads config.yaml at startup. The file is validated using Pydantic models -- if any required field is missing or a value has the wrong type, the server will exit with a clear error message.

Only server and home_assistant are required sections. All other sections have sensible defaults.

Server¶

server:
  host: "0.0.0.0"
  port: 8000

The HTTP/WebSocket server bind address and port.

Home Assistant¶

home_assistant:
  url: "http://192.168.1.100:8123"
  token: "your_long_lived_access_token_here"

Required

Both url and token are required. Without them, the domotica agent cannot control your devices.

To generate a long-lived access token:

Open your Home Assistant instance.
Go to your profile (click your name in the bottom-left).
Scroll to "Long-Lived Access Tokens" and create one.
Copy the token into config.yaml.

Keep your token secret

The config.yaml file contains your HA token. It is listed in .gitignore and should never be committed. The example file (config.yaml.example) uses a placeholder value.

Audio¶

audio:
  wake_word: "alexa"
  stt_model: "tiny"
  stt_language: "es"
  tts_voice: "/path/to/es_ES-davefx-medium.onnx"

Field	Default	Description
`wake_word`	`"alexa"`	openwakeword model name. The satellite listens for this word to start recording.
`stt_model`	`"tiny"`	faster-whisper model size. Options: `tiny`, `small`, `medium`, `large`.
`stt_language`	`"es"`	ISO language code for speech recognition.
`tts_voice`	`"es_ES-davefx-medium.onnx"`	Path to the Piper ONNX voice model file.

STT model tradeoffs

tiny -- fastest, lowest accuracy. Good for quick testing.
small -- good balance for most hardware.
medium -- better accuracy, requires more RAM.
large -- best accuracy, slowest. Needs a machine with plenty of RAM.

Models are downloaded from HuggingFace on first run and cached automatically.

LLM¶

Schakel supports two LLM backends: local (Ollama) and cloud (OpenAI-compatible). You can configure different models for each agent.

Local (Ollama)Cloud (OpenAI-compatible)

llm:
  ollama_url: "http://localhost:11434"
  router_model: "llama3:8b"
  general_model: "llama3:8b"
  domotica_model: "llama3:8b"
  musica_model: "llama3:8b"
  use_cloud: false

This is the default configuration. Make sure Ollama is running and the model is pulled:

ollama pull llama3:8b

You can use different models per agent. For example, a smaller model for the router (fast classification) and a larger one for general conversation.

llm:
  use_cloud: true
  cloud_provider: "openai"
  cloud_api_key: "sk-..."
  cloud_base_url: ""    # Leave empty for provider default
  cloud_model: ""       # Leave empty for provider default

Supported providers and their defaults:

Provider	Default model	Other options
`openai`	`gpt-5.4-mini`	`gpt-5.4-nano`, `gpt-5.1-mini`, `o3-mini`
`anthropic`	`claude-sonnet-4-6`	`claude-opus-4-6`, `claude-haiku-4-5-20251001`
`mistral`	`mistral-small-latest`	`mistral-large-latest`, `mistral-medium-latest`

Set cloud_base_url to use a custom endpoint (e.g., Azure OpenAI or a local proxy).

Mixing local and cloud

The use_cloud flag applies to the general agent only. The router, domotica, and musica agents always use the local Ollama backend for structured JSON output, as they need fast, deterministic responses. If you provide a cloud_api_key, the cloud LLM is initialized and available for the general agent when use_cloud: true.

Spotify¶

spotify:
  client_id: ""
  client_secret: ""
  redirect_uri: "http://localhost:8888/callback"
  token_cache_path: ".spotify_cache"

Field	Default	Description
`client_id`	`""`	From your Spotify Developer Dashboard app.
`client_secret`	`""`	The app secret from the same dashboard.
`redirect_uri`	`"http://localhost:8888/callback"`	OAuth redirect URI. Must match your Spotify app settings.
`token_cache_path`	`".spotify_cache"`	Path to cache the OAuth token locally.

After filling in the credentials, run the one-time OAuth flow:

uv run python -m app.services.music.spotify

This is entirely optional. If the client_id is empty, the Spotify client is not initialized and the music agent returns a friendly "not available" message.

Full Example¶

See config.yaml.example for a complete annotated configuration file, or check the Config Reference for a field-by-field table.