Piping your proprietary infrastructure manifests and internal automation scripts to cloud-hosted LLM endpoints is an unnecessary architectural and operational compromise. For years, running local inference meant wrestling with WebUIs that felt like glorified toy chatbots: neat for trivia, but completely disconnected from real terminal sessions, filesystems, and deployment pipelines.
The gap between interactive chat interfaces and actual developer utility comes down to one capability: autonomous tool calling. If an engine cannot natively read directory trees, run shell commands, inspect diffs, and manipulate codebases directly inside the project root, it remains an expensive autocomplete.
By wiring OpenCode directly to a local Ollama runtime on bare-metal hardware, you can deploy a zero-subscription, fully private AI coding agent that executes tasks directly in your terminal. Here is how to configure the stack, bypass integration pitfalls, and avoid critical model selection traps.
The Paradigm Shift: Chatbots vs. File-Aware Agents
Tools like Cursor, Claude Code, and the Codex CLI proved the value of deep repository awareness. However, relying on third-party SaaS pipelines exposes internal network layouts, Terraform state structures, and Kubernetes configurations.
OpenCode bridges this gap by bringing that exact terminal-native paradigm into a self-hosted environment:
- Autonomous Filesystem Traversal: The agent walks repository hierarchies to resolve relative dependencies and analyze project architectures without manual copy-pasting.
- Context-Driven Infrastructure Analysis: It parses Docker Compose files, Ansible playbooks, and PowerShell scripts natively within their working directories.
- Direct Task Execution: Instead of merely offering suggestions, the runtime issues terminal operations, executes inspections, and automates file-level modifications directly inside the local environment.
When paired with a locally served inference runtime like Ollama, this setup transforms home lab automation, Bash tooling, and Infrastructure-as-Code (IaC) maintenance into a self-contained feedback loop.
Installing OpenCode
Deploying the OpenCode engine requires minimal overhead. If your environment has a configured Python runtime, install the package directly:
bashpip install opencode-ai
The tool is equally accessible across various environments via binary distributions or Homebrew depending on your host OS.
Wiring OpenCode to Local Ollama Endpoints
Connecting OpenCode to a bare-metal Ollama instance requires an essential configuration workaround. The default OpenCode Text User Interface (TUI) includes built-in profiles for commercial endpoints (Azure OpenAI, OpenAI, Google Gemini, Anthropic, Mistral AI) and Ollama Cloud, but omits a pre-configured toggle for local Ollama instances.
To route requests to your local inference server, you must declare an OpenAI-compatible interface explicitly inside the configuration manifest.
Create or edit the opencode.json file at the OS-specific path:
- Linux / macOS:
~/.opencode/config/opencode.json - Windows:
%USERPROFILE%\.opencode\config\opencode.json
Populate the configuration with the local API endpoint:
json{ "api_endpoint": { "ollama": { "baseURL": "http://localhost:11434/v1", "model": "omnicoder:9b" } } }
The critical detail here is the baseURL syntax. OpenCode relies on Ollama's OpenAI-compatible /v1 endpoint structure. Pointing the path to http://localhost:11434/v1 ensures that tool declarations, payload serialization, and streaming completions match standard agentic conventions. Restart OpenCode, and your locally served model will appear in the active runtime picker.
The Model Selection Trap: Tool Calling is Mandatory
Deploying an agentic workflow introduces a strict architectural constraint: the underlying model must support native function calling.
Standard text completion models fail immediately inside agentic loops. For instance, running a model like DeepCoder 14B in this setup halts the workflow because the engine explicitly flags a lack of tool-use support.
To function as an active agent, the weights must be trained to output structured execution calls for tasks such as:
- Grepping and globbing project trees.
- Reading and writing raw files.
- Executing local bash/shell routines.
+-------------------------------------------------------------+
| OpenCode Agent Loop |
+-------------------------------------------------------------+
|
Structured Function Call Request
|
v
+-------------------------------------------------------------+
| Ollama Inference Endpoint |
| (e.g., omnicoder:9b) |
+-------------------------------------------------------------+
|
Tool Support Check: Pass (Structured JSON)
|
v
+-------------------------------------------------------------+
| Local Host Environment Operations |
| [Read / Write Files] [Glob Dirs] [Exec Bash] |
+-------------------------------------------------------------+
Switching to Omnicoder 9b resolves this bottleneck. With native tool-calling baked into the weights, the model reliably translates user prompts into structured file investigations and system actions.
Running Context-Aware Workflows
Agent performance depends on project context. To launch the runtime, traverse to your project root and initialize OpenCode directly from the shell:
bashcd my_docker_project opencode
By launching inside the repository root, the agent inherits the directory tree as its primary execution boundary.
User Prompt: "Can you check for any syntax errors in the Docker Compose files?"
Because the agent has direct filesystem access, it traverses the directory, inspects the Compose definitions, and flags syntax discrepancies without manual context loading.
The same mechanism simplifies multi-repository maintenance:
User Prompt: "Find all projects that use Packer templates."
User Prompt: "Give me security recommendations to tighten up security for the Packer projects."
If complex analysis exceeds the reasoning threshold of your local model, the environment allows hot-swapping endpoints on the fly. You can temporarily route the prompt to high-throughput cloud tiers such as the free DeepSeek V4 Flash endpoint for a second pass, and then switch immediately back to your local model.
Silicon Sizing: The VRAM Hardware Matrix
Running agentic models requires realistic compute budgeting. While general CPU inference is technically viable, high-latency execution makes CPU-based agentic workflows unworkable. Frequent context re-evaluations and multi-step tool calls demand dedicated GPU acceleration.
For 9B to 14B parameter quantized footprints, 16GB of VRAM represents the practical sweet spot for consumer hardware.
| Graphics Card | VRAM (GDDR) | PCIe Interface | Architectural Role & Practical Constraints |
|---|---|---|---|
| ASUS Dual GeForce RTX™ 5060 Ti OC Edition | 16GB GDDR7 | 5.0 | Best starting point for home lab environments. 16GB capacity comfortably hosts 9B to 14B quantized models. |
| GIGABYTE GeForce RTX 5070 WINDFORCE OC SFF | 12GB GDDR7 | 5.0 | Solid mid-range card with reliable cooling. The 12GB ceiling limits the execution of larger quantized models. |
| ASUS The SFF-Ready Prime GeForce RTX™ 5070 | 12GB GDDR7 | 5.0 | Tailored for Small Form Factor chassis layouts. Includes a dual BIOS switch for custom tuning. |
Running an RTX 5080 (16GB VRAM) provides ample overhead for models like Omnicoder 9b, delivering the low time-to-first-token latency required for iterative agent loops.
Architectural Boundaries and Trade-Offs
While a local OpenCode deployment delivers complete data privacy and zero API overhead, engineering teams must recognize the technical boundaries of current local weights:
- Long-Horizon Logic: Multi-step debugging across massive, multi-tiered architectures can degrade local model performance compared to frontier models.
- Context Capacity: Processing extremely large codebases in a single prompt window will bottleneck both VRAM allocation and generation accuracy.
- Refactoring Depth: Local agents excel at focused, scoped tasks such as IaC templates, configuration scripts, and single-service modules, but they are not designed to re-architect sprawling enterprise monoliths.
The Infrastructure Outlook
The definition of a standard home lab is shifting. The focus has expanded beyond hosting isolated hypervisors, K8s clusters, and network storage pools to treating hardware-accelerated local inference as a standard tier in the stack.
Configuring OpenCode with Ollama delivers a reliable, fully air-gapped developer agent directly in your terminal. As tool-calling support expands across smaller open-weight models, self-hosted coding agents will quickly become an essential utility for private, daily infrastructure engineering.