Local terminal agent · Ollama endpoint · repository tools
The fast path is one command. A reliable setup also needs a tool-capable model, at least 64K configured context for repository work, enough memory for that context and a safe Git workspace.
Fastest supported route
Install both applications from their official sources, make sure Ollama is running, then use the integration command:
ollama launch opencodeOllama asks you to choose an available model and starts OpenCode with an inline local configuration. The integration does not overwrite your persistent OpenCode configuration.
The check that prevents most false starts
Ollama's OpenCode documentation calls for a context window of 64K or higher. That context contains repository excerpts, tools, command output and history. A model can load successfully at a smaller window yet fail during real agent work.
Reproducible setup
Use the direct launch first. Add manual configuration only when you need a fixed model, another host or explicit context controls.
Download Ollama and follow the OpenCode installation guide for your operating system. Confirm both commands are available in a new terminal.
Autocomplete-only models are not automatically good agents. Check the model card for instruction following, tool or function calling and context support. Qwen3-Coder 30B-A3B is one current reference for agentic coding.
Run ollama list and use exactly the displayed name and tag. A different tag may point to a different parameter count or quantization.
Run ollama launch opencode, choose the local model and open a small test repository. Use ollama launch opencode --config if you want Ollama to prepare the configuration without starting an interactive session.
Ask the agent to read one file, make a small reversible edit and run a harmless test command. A fluent answer does not prove that structured tool calls work.
Watch memory use, prompt-processing delay, generation speed and test success. Reduce context or choose a smaller quantization if memory is exhausted; choose a stronger model if patches are fast but wrong.
Manual provider configuration
Create or update opencode.json when you want a fixed local provider. Replace both placeholders with the exact ID shown by ollama list.
{ "$schema": "https://opencode.ai/config.json", "provider": { "ollama": { "npm": "@ai-sdk/openai-compatible", "name": "Ollama (local)", "options": { "baseURL": "http://localhost:11434/v1" }, "models": { "your-model-id": { "name": "Your local coding model" } } } } }What each line changes
Do not replace localhost with a public bind address merely to make another device connect. Remote access needs authentication, firewall rules and deliberate network design.
Model + 64K context + headroom
OpenCode itself is not the main memory consumer. The loaded model, quantization, KV cache and parallel sessions set the hardware target.
| Local model class | Practical starting hardware | Suitable workload | Before you commit |
|---|---|---|---|
| 7B–14B quantized | 12–16 GB VRAM; 32 GB system RAM | Focused chat, small edits, first agent tests | Confirm 64K context fits and tools work reliably. |
| 20B–24B quantized | 24 GB VRAM; 64 GB system RAM | More capable single-agent work | Leave reserve for context, display use and build tools. |
| 30B–32B quantized | 32 GB VRAM for speed, or 64 GB+ unified memory for capacity | Repository agents and stronger code generation | The exact quantization may fit at 32K but become tight at 64K. |
| Large model or several agents | 96–128 GB unified/coherent memory | Capacity-first workflows and multiple services | Validate runtime support and expect a different speed profile from a discrete GPU. |
These ranges deliberately include working headroom but remain estimates. Use the actual model file, configured context and measured peak use. The PC Finder turns those inputs into a hardware class.
Troubleshooting by symptom
| Symptom | Likely cause | Check | Useful next move |
|---|---|---|---|
| Model not listed | Ollama is stopped, wrong tag or launch picker limitation | ollama list and the Ollama service | Pull the exact tag or define the installed ID in opencode.json. |
| Chat works, edits do not | Weak or incompatible tool calling | Model card and a one-file tool test | Use a tool-capable coding model; do not force capabilities the model lacks. |
| Out of memory after a while | Context cache or concurrent sessions | Configured context and peak memory | Close other sessions, reduce context deliberately or use a smaller quantization. |
| Very slow before first token | Long prompt ingest, CPU offload or cold model load | GPU offload, prompt length and storage activity | Keep the model in fast memory, reduce irrelevant context or choose a faster hardware path. |
| Agent repeats or loses files | Context truncation or weak repository retrieval | Actual context limit and OpenCode logs | Increase context only if memory allows; split the task and keep instructions concise. |
| Endpoint unreachable | Wrong host/port or service not running | http://localhost:11434/v1 and local firewall | Restore the default local endpoint before attempting remote access. |
Local inference is only one privacy layer
OpenCode can read files, edit them and run terminal commands. Treat model output like an untrusted junior contributor: useful, fast and always reviewed.
Use a clean branch or worktree and keep an easy rollback point.
Open only the project needed for the task; exclude credentials and production dumps.
Do not approve destructive, privileged or networked commands without understanding them.
Inspect the diff and run the project's tests, lint and security checks before merging.
OpenCode and Ollama FAQ
Yes. The local Ollama endpoint on localhost does not need a cloud-provider API key. Keep that endpoint local unless you deliberately add authentication and network controls.
An agent needs structured tool calls, more prompt context and enough output discipline to edit files and run commands. A model that writes convincing chat text may not support those operations reliably.
Ollama's official OpenCode integration recommends 64K or higher for local models. Small focused tasks may use less, but repository work can quickly fill the prompt with tools, files, output and history.
Choose the RTX 5090 when the model plus context fit in 32 GB and loop speed is the priority. Choose 128 GB unified memory when larger models, longer context or several services need capacity beyond 32 GB.
Keep commands current
Direct launch, the 64K context requirement, manual configuration and precedence. Open the official Ollama guide.
Provider syntax, local endpoint and tool-call troubleshooting. Open the official OpenCode guide.
Model architecture, native context, tool use and memory-error advice. Open the official model card.
Compare speed, capacity and exact complete systems in our local coding hardware guide.
Still choosing the PC?
Enter your model class, context and workload. The result separates fast dedicated VRAM from larger shared-memory capacity.