Skip to content

docs: explain cold-cache one-shot runs on OpenCode 2 #51

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yuseferi merged 1 commit into from
Oct 26, 2026
Merged

docs: explain cold-cache one-shot runs on OpenCode 2 #51

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -590,6 +590,35 @@ the plugin logs a warning and you won't see LiteLLM-discovered models until
the proxy is reachable again.
</details>

<details>
<summary><b>Why does the first <code>opencode run</code> fail with <code>Model unavailable: litellm/…</code> on OpenCode 2?</b></summary>

This happens only on OpenCode 2, in a one-shot command (`opencode run`, CI jobs, scripts), when the plugin has no model cache yet. That covers the first run, a cleared or expired cache, and a changed config or credential. OpenCode registers the providers declared under `providers.*` only after plugin setup returns, so the plugin can't discover their models during setup. Discovery starts right after that, but a one-shot command has already resolved its model and fails before the models arrive. With `--standalone`, the process usually exits before discovery reaches the disk cache, so running it again fails the same way. Interactive sessions (TUI, web, desktop) and `opencode serve` aren't affected. This is how the OpenCode host orders startup ([anomalyco/opencode#57421](https://github.com/anomalyco/opencode/issues/57421)), not a plugin bug.

Workarounds:

- **Warm the cache once.** Open an interactive session or run `opencode serve` until the models appear, then stop it. One-shot runs use the cache until it expires (7 days) or the config or credential changes.
- **Pass the connection as plugin options** for CI and scripts. Plugin options are available during setup, so discovery finishes before the command resolves its model, even with a cold cache:

```jsonc
{
"plugins": [
{
"package": "opencode-plugin-litellm@latest",
"options": {
"baseURL": "https://litellm.internal.example.com/v1",
"apiKey": "{env:LITELLM_API_KEY}"
}
}
]
}
```

One plugin entry describes one provider. To [split one proxy into several providers](#splitting-one-proxy-into-multiple-providers-includemodels--excludemodels) in a cold one-shot run, warm the cache first.

The OpenCode feature request for a readiness latch ([anomalyco/opencode#56119](https://github.com/anomalyco/opencode/issues/56119)) would remove the need for either workaround.
</details>

<details>
<summary><b>Will my hand-curated model entries be overwritten?</b></summary>

Expand Down
Loading