Configuration¶
ModelDeck uses two files in ./config (bind-mounted to /config in Docker):
| File | Purpose |
|---|---|
modeldeck.yaml |
MQTT, poll interval, enabled providers, auth_mode per provider |
secrets.yaml |
Passwords and provider tokens (chmod 600) |
Bootstrap with ops/bootstrap-config.sh (quickstart) or ops/bootstrap-config.sh production.
On Home Assistant OS, use the add-on Configuration tab instead of editing these files by hand (the add-on renders them on start).
For step-by-step credential extraction per provider, see credentials guide.
Auth modes¶
| Provider | auth_mode |
Credential | Source |
|---|---|---|---|
| codex | subscription |
access_token, refresh_token, account_id |
ChatGPT/Codex OAuth (~/.codex/auth.json or browser) |
| codex | api |
api_key (sk-admin-* Admin key) |
OpenAI Admin API |
| claude | cookie |
session_token (sessionKey), org_id (lastActiveOrg) |
claude.ai cookies (see ClaudeDash) |
| claude | oauth |
access_token, refresh_token |
Claude Code (~/.claude/.credentials.json) |
| cursor | personal |
session_token (WorkosCursorSessionToken) or access_token |
cursor.com/dashboard/usage or Cursor state.vscdb |
| cursor | enterprise |
admin_api_key |
Cursor team Admin API |
Set auth_mode: auto to pick the first mode with credentials (subscription/cookie/personal before api/enterprise).
Optional credential_path on each provider overrides the default CLI credential file location. Set credential_path: "" to disable file loading (secrets only).
Docker + CLI credentials¶
Bind-mount host credential dirs read-only, for example:
volumes:
- ./config:/config
- ~/.codex:/root/.codex:ro
Or paste tokens directly into config/secrets.yaml.
Enable a provider¶
- Set
enabled: trueandauth_modeinconfig/modeldeck.yaml. - Add credentials to
config/secrets.yaml. - Restart:
docker compose -f templates/docker-compose.yml restart. - Confirm
sensor.modeldeck_{provider}_statusisok. - Check
sensor.{provider}_usageandsensor.{provider}_usage_weeklywithin one poll interval (default 5 minutes).
Codex (OpenAI)¶
Subscription (ChatGPT Plus/Pro plan limits): use auth_mode: subscription. Copy OAuth tokens from ~/.codex/auth.json after signing in with the Codex CLI, or extract from ChatGPT browser session.
API billing (Platform organization spend): use auth_mode: api with an Organization Admin key (sk-admin-...). This tracks API costs in USD, not your ChatGPT subscription quota. See credentials guide.
Claude¶
Cookie mode (claude.ai web subscription): DevTools → Application → Cookies → copy sessionKey and lastActiveOrg.
OAuth mode (Claude Code): tokens load from ~/.claude/.credentials.json when credential_path is unset.
Tokens expire — renew when sensor.modeldeck_claude_status shows auth_error.
Cursor¶
Personal: copy WorkosCursorSessionToken from cursor.com dashboard cookies (CursorMonitor pattern).
Enterprise: Admin API key from team settings.
Collector status values¶
| Value | Meaning |
|---|---|
ok |
Last collection succeeded |
auth_error |
Missing or expired credential |
rate_limited |
Provider returned HTTP 429 |
parse_error |
Response shape unexpected |
unavailable |
Provider returned 5xx or transport failure |
MQTT broker¶
Set mqtt.host to your Home Assistant hostname or Mosquitto add-on IP. Add mqtt.password in secrets.yaml if required.