OpenCode with Ollama: verify one coding task before scaling up
Connect OpenCode to Ollama using the documented launch workflow, verify local versus cloud models, protect your repository and measure completed-task cost.
The documented quick route for connecting OpenCode to Ollama is ollama launch opencode. That is a configuration and launch workflow, not a guarantee that a particular local model fits your computer or will finish your coding task. Establish the selected model, context capacity and permission boundary before handing an agent a valuable repository. The useful outcome is a reviewed, passing change, not merely a terminal that accepts a prompt.
This walkthrough explains the decisions around the official setup rather than reproducing a long configuration file that may belong to a different OpenCode version. It also separates local runtime expense from hosted-model consumption. When the selected route uses Ollama cloud, compare the measured consumption with the monthly calculator. A local model needs hardware and time estimates instead.
Use the current integration route and inspect its effects
The Ollama OpenCode integration documents the launch command and a configuration-only variant, ollama launch opencode --config. It says the launch flow supplies inline configuration for the selected model without overwriting the existing OpenCode configuration file. Existing settings can still affect the session. Its local coding guidance recommends at least a 64k context window.
Install or update the tools through their official instructions before trying that workflow. Record the versions you are using and read any prompts. Do not grant an agent broad execution privileges simply to make the first test quiet. A coding tool can read files, edit them and invoke commands; choosing a local model does not remove those powers. Begin in a disposable example repository with no production credentials.
A compatibility matrix prevents mixed instructions
OpenCode documentation has version-specific provider configuration. The provider reference and the v2 model documentation should not be combined into an invented hybrid schema. Prefer the documented launch path when it supports your installed versions. If you choose manual setup, follow one matching version's instructions from beginning to end and validate its effective model selection.
| Decision | Evidence to save | Stop condition |
|---|---|---|
| Client configuration | Installed version and matching reference | Settings copied from conflicting versions |
| Model destination | Exact provider and model shown in session | Unexpected remote model or fallback |
| Context and memory | Effective context plus representative resource check | Severe swapping or repeated context failures |
| Repository access | Disposable directory and explicit allowed task | Request for unrelated secrets or broad changes |
| Acceptance | Reviewed diff and relevant test result | Only a confident natural-language completion claim |
These are acceptance criteria you can adapt, not measured product limitations. In particular, a selected model can be reachable yet unsuitable for tool use. A successful ordinary chat does not establish that the same model follows a structured tool-call loop correctly. Keep the first task deliberately small so you can recognize both an incorrect edit and an incorrect claim that no edit was necessary.
Run an inexpensive, inspectable first task
Create a small sample project with one pure function and a known failing test, then ask the agent to explain the failure before editing. Specify the relevant file and a narrow acceptance rule, such as correctly handling an empty input without changing normal behavior. Do not use the first experiment to migrate a database, publish a package or modify deployment credentials. Those tasks make mistakes harder to reverse and outcomes harder to inspect.
After the agent proposes or applies its change, review the diff and run the exact test you selected. Confirm the result comes from the current working tree rather than a pasted example. Then ask for one brief explanation of the change. Save whether the task passed, how many attempts it needed, and how long review took. This evidence supports a model decision better than comparing the length or confidence of two answers.
Why coding context is larger than your prompt
A short request can trigger reads of source files, tests and command output. Instructions, tool definitions and earlier observations can also occupy working context. Plan for this accumulation instead of equating a two-line user request with a two-line model input. The token guide explains the difference between human-visible text and the model's metered input.
The integration's 64k recommendation does not imply every computer can run every model at that setting. Model weights, active context, parallel work and the runtime all compete for resources. Choose a smaller bounded task if memory pressure becomes severe. Avoid blindly increasing context after every failure: an agent that rereads irrelevant files may need better scope rather than a larger allocation. Different official documentation versions can offer different starting values, so keep the installed version in your notes.
Compare cost per accepted change
Suppose a synthetic local session takes 18 minutes of machine time and 12 minutes of human review, while a hosted session takes 5 minutes of machine time and 6 minutes of review. Those invented values are not a benchmark or a claim about OpenCode. Their purpose is to show why token price alone is an incomplete comparison. If the local answer fails the test, its apparent zero API charge did not purchase a completed task.
Build a small ledger with separate columns for hosted usage, local resource allocation, review minutes, retries and accepted outcomes. For ten comparable tasks, divide each measured expense total by the number accepted, not by the number started. Keep human time in minutes if you do not want to assign it a monetary value. Do not add an arbitrary hourly rate and present the resulting amount as a provider charge.
Diagnose the failing layer
If the client cannot list or select the model, inspect provider configuration and reachability. If plain text works but tools fail, inspect protocol support, model capability and the matching integration version. If tool output arrives but the agent loses the task, inspect context growth and unnecessary file reads. If the agent reports completion but tests fail, treat that as an acceptance failure, not as proof of a networking issue.
When using a local endpoint with a cloud model, include the hosted account's status in the investigation. A local daemon can be healthy while the remote request fails. When a manual integration asks for a key, consult the authentication guide; never reuse an unrelated provider credential as a guess. Preserve redacted errors and the exact model identifier, but keep repository secrets out of public support tickets.
Frequently asked questions
Does launching OpenCode overwrite my existing configuration?
The current Ollama integration describes inline launch configuration rather than overwriting the existing OpenCode JSON file. Still inspect the effective session because existing settings remain relevant. Back up intentional manual changes before independently editing configuration.
Is a local coding agent automatically private?
No. Verify the model route and any network-enabled tools, plugins or services. Local inference is one boundary, while the agent's filesystem and network permissions are another. Both need review for sensitive work.
Can I choose the cheapest model without testing?
You can choose a low-cost starting candidate, but only a representative acceptance task establishes whether it works for your workflow. Repeat the same task and review criteria when comparing alternatives; different prompts are not a controlled comparison.
Sources: the linked Ollama integration and OpenCode provider/model references. Configuration details were checked on the date above; examples and decision tables are original planning guidance, not results from running OpenCode on this site.