Installation¶
Requirements¶
- Docker with Compose v2
- A reachable MQTT broker (Home Assistant Mosquitto add-on or standalone)
linux/amd64orlinux/arm64host (GHCR images are multi-arch)
Quick start (stable image)¶
From the repository root:
cp .env.example .env
./ops/bootstrap-config.sh # quickstart: mock provider for smoke test
# or: ./ops/bootstrap-config.sh production
docker compose -f templates/docker-compose.yml up -d
On Windows, use .\ops\bootstrap-config.ps1 instead of the shell script.
This pulls ghcr.io/automationnexus/modeldeck:latest by default. Edit config/modeldeck.yaml and config/secrets.yaml before or after first boot.
Smoke test then real providers¶
- Quickstart (
bootstrap-config.sh) — mock data only; confirm HA entities appear. - Production — re-run
bootstrap-config.sh productionor copytemplates/modeldeck.example.yamltoconfig/modeldeck.yaml, fillconfig/secrets.yaml, restart the container. - Verify
sensor.modeldeck_{provider}_statusisokfor each enabled provider. - Paste dashboard YAML from
examples/home-assistant/(Overview + ModelDeck tab) — dashboard.md.
See configuration.md for Codex, Claude, and Cursor credentials.
For step-by-step token extraction (browser, CLI, HAOS), see credentials.md.
Home Assistant OS add-on¶
On HAOS, install from the dedicated add-on repository instead of Docker Compose:
- Add repository
https://github.com/automationnexus/ModelDeck-HAOS(Settings → Add-ons → Repositories) - Install ModelDeck, configure MQTT + credentials in the Configuration tab
- Start the add-on and verify MQTT sensors
Full walkthrough: ModelDeck-HAOS.
Local build (contributors)¶
./ops/bootstrap-config.sh
docker compose -f templates/docker-compose.build.yml up --build -d
Nightly image (dev testers)¶
Set IMAGE_TYPE=nightly in .env, then run compose as above.
Home Assistant¶
Ensure the Mosquitto broker is running. ModelDeck publishes MQTT Discovery sensors on startup.
See home-assistant.md.