dsh-ollama-cloud-usage
English | 中文
DeepSeek Harness plugin that shows the remaining Ollama Cloud quota as a Settings section, and lets you enter or replace the Ollama Cloud API key right on that page. The section registers as settings.section with id ollama-quota and order: -9, so it sits directly below the shipped Account / 账号与余额 entry. (The account page itself declares no child slot, so a plugin cannot append a card inside it; a sibling section is the supported placement.)
What it shows
| Row | Source field |
|---|
| Session window remaining | limits.session.usage (fraction in [0, 1]) |
| Weekly window remaining | limits.weekly.usage |
| Per-model request counts | limits.<window>.models[].request_count |
| Last-4-weeks cost and period | activity.cost, activity.period |
| Key source | which credential reference resolved |
| API key editor | credentials.describe / credentials.set / credentials.unset over the DSH Remote |
Data comes from GET https://ollama.com/api/usage with Authorization: Bearer <key>. That is the endpoint behind the "Cloud usage" panel of ollama.com/settings; the local daemon at 127.0.0.1:11434 has no quota route. The response carries no plan label and no reset timestamps.
Install
From npm:
dsh plugin --profile <profile> add dsh-ollama-cloud-usage
From a checkout:
npm pack --pack-destination dist
dsh plugin --profile <profile> add "$(pwd)/dist/dsh-ollama-cloud-usage-0.2.0.tgz"
The install reconciles dsh.profile.bundles and the profile applies the new layer. If the Host row does not appear, restart the app; an updated Client half needs a page refresh (the Desktop app has no client-bundle watcher).
Custom API key
The section's API key card writes to the first credential reference in keyEnvs through the shipped credentials Remote — the same write path the Models settings section uses. Saving stores the key in $DSH_HOME/.credentials.yaml and immediately re-reads the quota; Clear removes it.
- The card shows the reference name, whether it is configured, and the source layer (
env, file, …).
- A reference shadowed by a read-only source (a process environment variable) is reported read-only instead of silently writing to the fallback reference.
- The key is never rendered back: the input is always empty, and the snapshot route returns no secret.
- A client without the
credentials Remote falls back to a manual-configuration hint.
Configuration
The plugin row reads these fields, all optional:
| Field | Default | Meaning |
|---|
keyEnvs | [OLLAMA_CLOUD_API_KEY, OLLAMA_API_KEY] | credential references tried in order; the first is the one the editor writes |
usageUrl | https://ollama.com/api/usage | usage endpoint |
refreshMs | 60000 | snapshot refresh interval, minimum 5000 |
timeoutMs | 15000 | per-request timeout |
Example profile patch entry:
- id: ollama-cloud-usage
config:
refreshMs: 120000
Credentials
The key is resolved through ctx.credentials, so it can live in the process environment, $DSH_HOME/.env, or the refs section of $DSH_HOME/.credentials.yaml:
version: 1
refs:
OLLAMA_CLOUD_API_KEY: <key from https://ollama.com/settings/keys>
A missing key is not an error: the section renders the editor and a configuration hint. The key never reaches the browser — the snapshot route returns window fractions, request counts, the activity cost, the reference order, and error labels only.
Layout
| File | Role |
|---|
index.js | Host half: credential resolution, /api/usage polling, JSON snapshot route |
client.js | Client half: the settings.section registration, quota UI, and key editor |
cordis.patch.yml | bundle patch inserting the plugin row |
Verification
node --check index.js && node --check client.js
node scripts/verify.mjs
scripts/verify.mjs drives both halves offline: the Host route paths (healthy, missing key, unauthorized, transport failure, credentials/updated refresh) and the Client component rendered against a hook-faithful React stub, including the key editor's describe/save/clear calls, the read-only branch, and locale switching.
Known Limitations and Deferred Work
ollama.com/api/usage is unofficial but stable; the payload carries no plan name and no reset timestamps, so the page shows window usage only.- The usage endpoint is polled and refreshed on
credentials/updated; there is no push channel.
- Only the first reference in
keyEnvs is editable. Additional references remain configuration-only.
