Provider credentials¶
ModelDeck does not log you in. You authenticate once in a browser or CLI, copy tokens or cookies into config/secrets.yaml, and ModelDeck reuses them on each poll.
Choose the right auth mode¶
| You pay for… | Provider | auth_mode |
Official API? |
|---|---|---|---|
| ChatGPT Plus/Pro / Codex subscription | codex | subscription |
No — community pattern (openusage) |
| OpenAI Platform API billing | codex | api |
Yes — Organization Costs API (sk-admin-* key) |
| claude.ai Pro/Max (web) | claude | cookie |
No — console API (ClaudeDash) |
| Claude Code subscription | claude | oauth |
No — Claude Code OAuth usage endpoint |
| Cursor personal Pro/Ultra | cursor | personal |
No — session cookie or app JWT (CursorMonitor) |
| Cursor Team / Enterprise | cursor | enterprise |
Yes — Cursor Admin API |
Subscription modes show the same % bars as the provider website (5h / 7d). API modes show billing or spend, not consumer subscription quotas.
Which sensors appear¶
ModelDeck discovers only metrics your auth mode can populate. See sensors.md for the full matrix. Examples:
| Auth mode | Typical sensors |
|---|---|
Codex subscription |
usage, usage_weekly, resets, plan |
Codex api |
usage_used, plan (no % bar) |
Claude cookie / oauth |
usage, usage_weekly, optional usage_used/usage_limit from extra-usage |
Cursor personal |
usage, usage_auto, usage_api, used/limit, reset |
Cursor enterprise |
usage, used/limit, reset, plan |
Quick setup (all providers)¶
- Set
auth_modeinconfig/modeldeck.yaml. - Paste credentials into
config/secrets.yaml(chmod 600). - Restart:
docker compose -f templates/docker-compose.yml restart - Confirm
sensor.modeldeck_{provider}_statusisok. - Check
sensor.{provider}_usageandsensor.{provider}_usage_weeklywithin one poll interval.
CLI helper (on a machine with credential files)¶
modeldeck credentials print --all
modeldeck credentials print --provider codex --full
modeldeck credentials print --all --write-secrets # merge into config/secrets.yaml
Codex (OpenAI)¶
Subscription (auth_mode: subscription)¶
Tracks ChatGPT/Codex plan limits (5h / 7d windows).
Option A — Codex CLI (recommended)
- Install and sign in: Codex CLI
- Copy tokens from
~/.codex/auth.json(or~/.config/codex/auth.json):
providers:
codex:
access_token: "eyJ..."
refresh_token: "rt_..."
account_id: "user-..."
Option B — Docker bind-mount
volumes:
- ./config:/config
- ~/.codex:/root/.codex:ro
Leave credential_path unset; ModelDeck reads /root/.codex/auth.json inside the container.
Option C — Browser extraction
Extract OAuth access_token from an authenticated ChatGPT session (advanced; same tokens as Codex CLI stores).
Official docs: none for this endpoint.
API (auth_mode: api)¶
Tracks Platform organization spend (USD), not ChatGPT subscription %.
- Open Organization Admin Keys
- Create a read-only admin key (
sk-admin-...) - Paste into
secrets.yaml:
providers:
codex:
api_key: "sk-admin-..."
Official docs: Usage and costs
Warning
Standard project keys (sk-proj-...) and user keys (sk-...) do not work for usage/cost APIs.
Claude¶
Cookie (auth_mode: cookie)¶
For claude.ai Pro/Max subscribers.
- Sign in at claude.ai
- Open DevTools → Application → Cookies →
https://claude.ai - Copy all four cookies (not just the first two — the Cloudflare and device cookies are what get you past HTTP 403):
sessionKey→session_tokenlastActiveOrg→org_id(a UUID is normal)cf_clearance→cf_clearanceanthropic-device-id→device_id
providers:
claude:
session_token: "sk-ant-sid01-..."
org_id: "..."
cf_clearance: "" # paste cf_clearance; required for many 403s
device_id: "" # paste anthropic-device-id when present
Docker + cookie mode
cf_clearance is bound to the IP and User-Agent that solved the
Cloudflare challenge. When ModelDeck runs in Docker, the container's
outbound IP differs from your browser, so claude.ai can still return
403 even with correct cookies. If 403 persists after re-copying all
four cookies, run ModelDeck on the same host/IP as the browser. Use
modeldeck credentials verify --provider claude to confirm the live
status and hint.
OAuth (auth_mode: oauth)¶
For Claude Code subscribers only. claude.ai Pro/Max web subscriptions
use cookie mode above, not oauth.
- Sign in with Claude Code CLI on a machine with
~/.claude/.credentials.json - Copy
claudeAiOauth.accessTokenandrefreshToken, or bind-mount the file:
providers:
claude:
access_token: "..."
refresh_token: "..."
Official docs: none for the OAuth usage endpoint (undocumented).
Cursor¶
Personal (auth_mode: personal)¶
Option A — Dashboard cookie (easiest)
- Sign in at cursor.com/dashboard/usage
- DevTools → Cookies → copy
WorkosCursorSessionToken
providers:
cursor:
session_token: "..."
Option B — App JWT
Copy cursorAuth/accessToken from Cursor state.vscdb:
| OS | Path |
|---|---|
| Linux | ~/.config/Cursor/User/globalStorage/state.vscdb |
| macOS | ~/Library/Application Support/Cursor/User/globalStorage/state.vscdb |
| Windows | %APPDATA%\Cursor\User\globalStorage\state.vscdb |
providers:
cursor:
access_token: "eyJ..."
Enterprise (auth_mode: enterprise)¶
Team / Enterprise admins only. Personal accounts must use personal.
- cursor.com/dashboard → Settings → Advanced → Admin API Keys
- Create key (
crsr_...orkey_...format) - Paste:
providers:
cursor:
admin_api_key: "crsr_..."
Official docs: Admin API — Get Spending Data
Home Assistant OS¶
Add-on Configuration tab (recommended)¶
Install the ModelDeck add-on (haos-addon guide) and paste credentials in Settings → Add-ons → ModelDeck → Configuration. MQTT host defaults to core-mosquitto when using the official Mosquitto add-on.
File-based setup¶
- Edit
config/secrets.yamlvia Samba, SSH, or the File Editor add-on. - Use
modeldeck credentials printon your PC, then paste the YAML block. - For CLI credential files, bind-mount read-only into the container (see Codex example above).
- Set
IMAGE_TYPE=nightlyin.envfor latestdevfeatures until the next release tag.
Token refresh¶
Codex subscription and Claude OAuth collectors refresh tokens on HTTP 401.
| Mechanism | Config key | Default | When |
|---|---|---|---|
| Runtime token persist | service.persist_refreshed_tokens |
true |
During polling — writes refreshed OAuth tokens to secrets.yaml |
| Configuration Save merge | reset_secrets = false |
off (HA add-on) | Each Save merges UI into on-disk secrets; empty password fields do not wipe OAuth tokens |
| Full replace on Save | reset_secrets = true |
— | Replaces secrets with form only — use only when rotating credentials |
When persist_refreshed_tokens is true (default) and secrets.yaml is writable, refreshed tokens survive container or add-on restarts without re-pasting from the UI.
Docker: ensure ./config is bind-mounted read-write (default in templates/docker-compose.yml).
Troubleshooting¶
collector_status |
Action |
|---|---|
auth_error |
Re-copy token/cookie; check auth_mode matches account type |
rate_limited |
Wait and retry; reduce poll frequency |
parse_error |
Provider changed API shape; check GitHub issues |
unavailable |
Provider outage or network issue |
| Symptom | Fix |
|---|---|
Codex api fails with 401 |
Use sk-admin-* key, not sk-proj-* |
| Claude 403 (cookie) | Copy all 4 cookies incl. cf_clearance; in Docker, run on the browser's host/IP |
| Cursor enterprise 403 | Confirm Team/Enterprise plan and admin key scope |
| Weekly sensor empty | Normal for Cursor personal (billing cycle only) |
Manual smoke checklist¶
After configuring credentials:
- [ ]
sensor.modeldeck_codex_status=ok - [ ]
sensor.modeldeck_claude_status=ok - [ ]
sensor.modeldeck_cursor_status=ok - [ ]
sensor.modeldeck_codex_usage_percentshows a percentage (subscription) or spend (api) - [ ]
sensor.modeldeck_codex_usage_weekly_percentpopulated (subscription) - [ ]
sensor.modeldeck_claude_usage_weekly_percentpopulated (cookie/oauth) - [ ] Tokens survive container restart (OAuth refresh persistence)