dsh-ollama-cloud

dsh-ollama-cloud

English | 中文

Ollama Cloud provider for DeepSeek Harness: install it and the provider is configured — with per-model thinking strength you can actually adjust.

Chat runs on Ollama's OpenAI-compatible surface (https://ollama.com/v1), model discovery reads Ollama's own native API (/api/tags, /api/show), and Ollama's web search/fetch endpoints register as harness ctx.web providers. The thinking levels each model publishes (off / low / high / max, …) come straight from that model's thinking wire metadata, so the composer's Effort selector adjusts real capability instead of a guess.

The catalog is not frozen at release either. On every mount the plugin asks the configured endpoint what it serves and adopts the answer for the running session, then caches it for the next boot; a long-running session refreshes again on an interval. A model Ollama adds, retires, or re-levels therefore reaches you without waiting for a plugin update.

Install

# Prebuilt tarball (recommended: no build authorization needed)
dsh plugin --profile web add --force \
  https://github.com/Asheblog/dsh-ollama-cloud/releases/latest/download/dsh-ollama-cloud.tgz

# Or straight from GitHub sources (build artifacts are tracked in the repo)
dsh plugin --profile web add github:Asheblog/dsh-ollama-cloud

Restart the harness, then give Ollama Cloud an API key in Settings → Models (stored write-only through the credentials service), or export one:

export OLLAMA_API_KEY=...        # Linux / macOS
$env:OLLAMA_API_KEY = "..."      # Windows PowerShell

Keys come from . The catalog and metadata endpoints are anonymous, so the model list appears before any key exists — only chat fails, with MISSING_CREDENTIAL.

Pick one of this plugin or `dsh-llm-ollama`. Both register the ollama-cloud route, and installing both fails at mount time (DUPLICATE_ADAPTER). Remove dsh-llm-ollama from the profile's bundles first.

Usage

1. Pick an ollama-cloud model in the composer's model menu (or /model).
2. Pick an effort in the same menu. The offered levels depend on the model, and the default comes from Ollama's own model metadata.
3. Thinking streams into the transcript like any other provider. The effort is stored per session; a running step keeps the level it started with.

The catalog: the endpoint is the authority

Ollama adds and retires cloud models on its own schedule, so this plugin does not treat its own release as the model list. Every mount asks the configured endpoint what it serves — GET /api/tags for membership, POST /api/show for each model's context window, input modalities, and the thinking ladder plus default that model itself declares — and serves that answer. The layers, highest first:

Layer · What it decides Your models configuration · per-id overrides, additions, and enabled: false retirements The endpoint, just fetched · which models exist, and every capability each one declares The cache of the last fetch · the same answer, read from disk before the network answers The shipped snapshot · display names, and the fallback until some fetch has succeeded

Two consequences worth knowing:

• A retired model leaves by itself. A model the endpoint stops listing disappears, and one its listing still names but answers 404/410 for is dropped too — that answer is the endpoint saying its own listing is stale. A detail request that merely *fails* (timeout, 5xx, 429) keeps the model with what the listing said: a slow /api/show must not hide a real model for a whole refresh interval.
• New models arrive with their own levels. A model the snapshot never shipped keeps its id as the display name until a release gives it a prettier one; its thinking levels are still whatever /api/show reports.

What ships is the snapshot a session falls back to before its first successful fetch — live GET https://ollama.com/api/tags + POST https://ollama.com/api/show metadata taken 2026-09-29:

Model · Context · Vision · Levels · Default deepseek-v4.1-flash · 1,048,576 · ✔ · Off / Low / High / Max · High deepseek-v4-pro:0813 · 1,048,576 · — · Off / Low / High / Max · Low kimi-k3 · 1,048,576 · ✔ · Off / Low / High / Max · Max kimi-k2.6 · 262,144 · ✔ · Off / High · High kimi-k2.7-code · 262,144 · ✔ · Off / High · High glm-5.3 · 1,048,576 · — · Low / High / Max · Max glm-5.3-flash · 1,048,576 · ✔ · Low / High / Max · Max glm-5.2 · 1,048,576 · — · Off / High / Max · High gpt-oss:120b · 131,072 · — · Low / Medium / High · Medium gpt-oss:20b · 131,072 · — · Low / Medium / High · Medium minimax-m3 · 512,000 · ✔ · Off / Low / Medium / High / Max · — minimax-m2.7 · 196,608 · — · High · High nemotron-3-ultra · 262,144 · — · Off / High · High nemotron-3-super · 262,144 · — · Off / High · High nemotron-3-nano:30b · 262,144 · — · Off / High · High gemma4:31b · 262,144 · ✔ · Off / High · Off mistral-large-3:675b · 262,144 · ✔ · (no thinking control) · —

Models whose metadata is a boolean switch (kimi-k2.6, gemma4:31b, …) expose Off and High only — on the wire, High means "thinking on". minimax-m2.7 reports [true], so thinking cannot be switched off and only High is offered. minimax-m3 reports the thinking capability without a level ladder, so it takes the standard ladder and claims no default; the same applies to any model neither the catalog nor your configuration describes.

Refreshing the catalog

On by default, and nothing about it blocks a boot:

• At mount — one refresh as soon as the route is up. The model list is already correct before it lands, because the cache below answers first.
• On an interval — refreshMinutes later (default 1440, i.e. daily), and again after each pass. Every pass re-reads the live configuration, so switching the refresh off or changing the interval applies at the next tick instead of requiring a reload; while it is off (or mount-only) the scheduler still ticks every few minutes without touching the network, so switching it back on is honored the same way.
• The cache — /cache/dsh-ollama-cloud/catalog.json, resolved through the harness's own home helper: written atomically, validated on read, ignored when it is malformed or belongs to another endpoint. It lives outside the installed package, so updating the plugin keeps it, and it is what an offline restart — or any restart's first second — is served from.

Turn the whole thing off with autoRefresh: false: the route then serves the cache of the last fetch (or the shipped snapshot before any fetch), and never opens a connection on its own — the honest setting for an air-gapped or quota-limited deployment. refreshMinutes: 0 keeps the mount refresh and drops the periodic one.

The manual surfaces remain:

• Discover from the endpoint: any surface calling llm/discoverModels lists what the endpoint currently serves, with context windows and input modalities. Only models /api/show can fully describe become candidates.
• Edit by hand: override models in the plugin configuration (below). enabled: false hides a shipped model.

Cloud usage in the UI

The plugin ships a browser half that renders in the host's own surfaces — no separate page, and no provider-UI shell plugin needed:

• Models page card: inside the Ollama Cloud row (Settings → Models), one

meter per billing window the plan has, each with its remaining share and reset line, the write-only API key field, and a refresh button.

• Sidebar row: a compact remaining-quota progress bar under the session

list — the label and percentage on one line, the bar beneath it, filled with what is *left* and graded by the remaining share (ok / warn / critical) so a shrinking bar reads the same way as the number. Click it for the per-window detail; a hover title carries the reset line. It refreshes when the sidebar mounts and every 15 minutes after that, and the collapsed 56px rail keeps the mini bar plus the percentage with no label.

The card reads the account's allowance from GET /balance through this plugin's own host channel (/ollama-cloud), so the API key stays on the host and never reaches the browser. That endpoint reports what is *left* of each window, and the panel draws the complement; which of its three windows a plan has is the endpoint's answer, so a plan that reports a monthly one gets a third meter with no plugin change. A local or self-hosted endpoint answers 404 on /balance; that renders as "this endpoint does not report cloud usage" rather than an error, and the last good snapshot keeps showing instead of disappearing. A read that fails transiently (a reset connection, a rate limit, a 5xx from the endpoint or from something in front of it) is retried once, and a failed row polls every minute until it recovers, because one bad moment should not leave a wrong number on screen for a whole cadence. Hover a failure line to see the machine diagnostic behind it.

The usage channel needs the composition's connection row to inject

webServer; this bundle's patch adds that (profiles without a connection row

skip it). After installing or updating the plugin, restart the harness once —

until then the card says so itself.

Configuration

Every field is editable from the plugin settings page and overridable per row in the profile's cordis.patch.yml:

- id: llm-ollama-cloud
  name: 'dsh-ollama-cloud'
  config:
    apiKeyEnv: OLLAMA_API_KEY        # credential reference; empty string = no auth (local servers)
    baseURL: https://ollama.com/api  # native API root; local Ollama: http://localhost:11434/api
    maxTokens: 32768                 # output cap for models that declare none
    defaultContextWindow: 262144     # context fallback for models that declare none
    streamIdleTimeoutMs: 300000      # maximum idle time between stream reads
    requestTimeoutMs: 15000       # per-attempt budget for the non-chat requests (discovery, web search/fetch)
    autoRefresh: true                # refresh the catalog at mount and on the interval
    refreshMinutes: 1440             # minutes between refreshes; 0 = refresh at mount only
    retryPolicy:                     # executed by dsh-llm-retry
      mode: normal
      maxRetries: 5
    models:                          # merges over the live catalog by id; new ids append
      - id: gpt-oss:20b
        contextWindow: 131072
        reasoningEfforts: { off: none, low: low, medium: medium, high: high }
        defaultEffort: medium
      - id: brand-new-model          # a model newer than the snapshot
        name: Brand New
        contextWindow: 131072
        reasoningEfforts: { off: none, high: high }
        defaultEffort: high
      - id: retired-model            # retire a shipped model
        enabled: false

Field semantics:

• autoRefresh and refreshMinutes control the catalog refresh described above. Both are read live, so a change takes effect at the next scheduled tick — see that section for what "off" still ticks for.
• models merges over whatever catalog is in force — the endpoint's live answer, or the shipped snapshot when no fetch has succeeded — and always wins by id, so enabled: false retires a model the endpoint still serves.
• reasoningEfforts keys are the levels the picker offers (off, minimal, low, medium, high, xhigh, max); values are the spellings sent to Ollama (off: none). false declares a model with no thinking control; omission inherits the live entry's levels, and an id neither the endpoint nor the entry describes takes the standard ladder (off/low/medium/high/max) with no default claimed.
• defaultEffort must be one of the offered levels. It is materialized when a session picks none; otherwise the model's own default applies.
• An override inherits the in-force default level only while it leaves reasoningEfforts alone — changing the level set makes the declaration authoritative.
• A declared defaultEffort outside the offered set fails at mount instead of degrading silently.

Local Ollama / self-hosted endpoints

- id: llm-ollama-cloud
  config:
    baseURL: http://localhost:11434/api
    apiKeyEnv: ''                     # a local server needs no bearer token

baseURL is normalized: a bare host gains /api, a /v1 spelling maps back to /api, and an explicit custom path (https://gateway.example/ollama) is kept as written.

Web search and fetch

The plugin registers Ollama's /api/web_search and /api/web_fetch as ctx.web providers — registering changes no deployment policy. To use them:

- id: web
  config:
    searchProvider: ollama-cloud
    fetchProvider: ollama-cloud

Both share the route's credential reference and baseURL. Requests carry the credential, so redirects fail closed; each attempt has a 15-second budget and one retry on a transient pre-response transport failure.

Compatibility

• Verified against DSH 0.2.1-rc.1, 0.2.1-rc.2, and 0.2.1-rc.3. engines.dsh is >=0.2.1-rc.1 — the first release whose connection row injects webStartup — so the 0.2.0 line is outside this release (next bullet). The per-release verdicts live in dsh.compatibility.dshReleases, and a future regression is recorded in dsh.compatibility.blocklist.
• The bundle patch follows the composition's `connection` row. connection.rpc.handle() mounts a channel through that row's own webServer — a caller that injects webServer on its own row still throws cannot get property "webServer" without inject — so this bundle restates the row's inject list with webServer added. That list also carries the row's startup dependency, and that one is the composition's to change: the 0.2.0 line injects webRuntime, 0.2.1-rc.1 injects webStartup. A stale name there does not fail a request; it makes a required row wait forever and fails the whole boot, which is why pnpm test compares this patch with the installed @deepseek-ai/dsh-web-app composition (tests/composition.test.ts) and engines.dsh admits only the releases whose row injects webStartup. Rationale and rejected alternatives: ADR 0008.
• Runtime dependency: @earendil-works/pi-ai, declared at the generation the installed harness speaks (^1.1.0 for harness 0.2.1-rc.3; the lockfile resolves 1.4.0, a later minor that range admits). pi-ai is not a host-shared package, so this copy and the harness's own only agree while their generations do. The route normalizes the request context at its own boundary, which is the contract that changed between harness generations, so a 0.2.1 host drives it natively and the shim still absorbs a pre-0.87 context from an older one; pnpm check and the scheduled pi-ai-drift workflow fail when the two declared ranges admit no common version, and the plugin logs one mount-time warning when it can reach the installed harness's declaration and this build falls outside it (best-effort: a host that hides its manifest reads as silence, and CI is the reliable signal). Rationale: ADR 0004.
• Protocol translation, streaming, replay, and tool calls are delegated wholesale to the official @deepseek-ai/dsh-llm-pi-ai PiAiAdapter; this plugin contributes Ollama-specific connection facts, the model catalog, and level metadata. Rationale: ADR 0001.
• The browser half renders only in host slots (settings.models.provider-card, sidebar.footer.action) with host theme tokens, declares connection in its inject, and requires no other client package: the usage channel (/ollama-cloud + usage/read) is the plugin's own, so no provider-UI shell has to exist for the card to work.
• Known limits: Ollama's OpenAI-compatible surface supports neither tool_choice nor logprobs, and reports no prompt-cache statistics; usage is whatever it actually returns. The catalog cache holds one endpoint at a time — pointing baseURL at a second endpoint serves the shipped snapshot until that endpoint answers.
• The model list, every model's context window and input modalities, and every thinking ladder come from the configured endpoint (/api/tags + /api/show), refreshed at mount and on an interval; the shipped snapshot only fills a display name for an id it already knew, and the gap before the first successful fetch. Rationale: ADR 0005.

Development

pnpm install
pnpm check        # typecheck + tests + build
pnpm run check:live   # the real allowance endpoint, end to end (needs the key)
pnpm pack         # produce the tarball
node scripts/check-tarball.mjs   # verify the artifact is independently installable

The repo tracks the lib/ build artifacts, so a GitHub-source install needs no build authorization. The loader row id is llm-ollama-cloud, which is also the settings namespace.

License

MIT