Claude Code with Ollama and Local Models: What Actually Works in 2026

Written against Claude Code 2.1.263 and Ollama 0.33.3, both verified by running them locally on 6 September 2026, plus the official Anthropic and Ollama docs. This area moves faster than almost anything else I write about; check versions before copying commands.

Overview

The question comes up every week in the community: can I run Claude Code against a model on my own machine, and should I.

The first half is now genuinely easy. Ollama ships an Anthropic-compatible API, so two environment variables are enough. The second half is where the honest answer lives, and the short version is: it works, it is not supported by Anthropic, several features you rely on silently stop existing, and the result is a noticeably less capable agent.

That can still be the right trade. This post covers what actually happens so you can decide.

Prerequisites

• Claude Code installed. claude --version should print something.
• Ollama installed. ollama --version printed 0.33.3 on my machine; that is the version pinned in the House of Loops course stack, and the current release as of 2 September 2026. The Docker image tag is ollama/ollama:0.33.3, do not use latest.
• Enough hardware, or a willingness to use Ollama's cloud models. See the hardware section below before you commit.

1. Start With What Anthropic Says

Before the setup, the sentence that should shape your expectations. From Anthropic's own gateway documentation:

Anthropic doesn't endorse, maintain, or audit third-party gateway products, and doesn't support routing Claude Code to non-Claude models through any gateway.

That is not a warning that it will fail. It is a statement that it is out of scope. When a tool call comes back malformed, when a subagent loops, when an edit gets applied to the wrong file, you cannot open a support ticket and you cannot assume the behaviour is a bug rather than the model.

Claude Code has an officially supported set of third-party providers, Amazon Bedrock, Google Cloud, Microsoft Foundry, but those all serve Claude models. That is a different thing from running Claude Code on a Qwen model on your laptop.

Everything below is the unsupported path. Go in with that framing and you will have a much better time.

2. The Direct Path: Ollama's Anthropic-Compatible API

This is the part that changed and made most older tutorials obsolete. Ollama now implements the Anthropic Messages API at /v1/messages, specifically to connect tools like Claude Code.

2.1 The one-command version

Ollama 0.33.3 ships a launch subcommand with a Claude Code integration built in. Verified from ollama launch --help on my machine:

ollama launch claude

That prompts you to pick a model, configures Claude Code, and starts it. To write the configuration without launching:

ollama launch claude --config

For scripts, Docker or CI there is a non-interactive form. The --yes flag skips the selectors and pulls the model if needed, and requires --model. Anything after -- is passed straight through to Claude Code:

ollama launch claude --model glm-4.7:cloud --yes -- -p "how does this repository work?"

2.2 The manual version

If you would rather see what is happening, it is two variables:

export ANTHROPIC_AUTH_TOKEN=ollama    # required, but Ollama does not validate it
export ANTHROPIC_BASE_URL=http://localhost:11434

Then:

claude --model qwen3-coder

Pull the model first:

ollama pull qwen3-coder

To confirm Claude Code is actually pointed at Ollama rather than your normal account, run /status inside the session. The Status tab shows an Anthropic base URL line only when a base URL is set. If that line is missing, your variables did not reach the process.

One useful trick from Ollama's docs: for tooling that insists on real Anthropic model names, copy a model under an alias.

ollama cp qwen3-coder claude-3-5-sonnet

2.3 Which model

Ollama's own recommendations for coding are glm-4.7, minimax-m2.1 and qwen3-coder. Two caveats they state plainly and that most blog posts skip:

• qwen3-coder is a 30B-parameter model that needs at least 24 GB of VRAM to run smoothly, and more for longer context.
• For anything larger than a toy repository, set the context length to 64k or higher. Claude Code fills a context window quickly, file reads, tool results, CLAUDE.md, skill content, and a 8k or 16k window will fall over on the first real task.

If your machine cannot do that, Ollama's cloud models (glm-4.7:cloud, minimax-m2.1:cloud) run through the same endpoint without downloading anything. That is a perfectly reasonable middle ground, but be clear with yourself: at that point the privacy argument is gone, and you are simply choosing a different vendor.

3. What Breaks

This is the section I wish existed when I first tried it. Ollama publishes a compatibility table for its Anthropic endpoint, and the gaps matter more than the checkmarks.

Prompt caching is not supported. No cache_control blocks. On the hosted service, Claude Code caches large stable prefixes, your system prompt, CLAUDE.md, the files already read, so a long session gets cheaper and faster as it goes. Without caching, every turn re-processes the whole conversation. On a local GPU this is the single biggest reason long sessions feel like wading through mud.

tool_choice is not supported. You cannot force a specific tool or disable tools for a request. Claude Code leans on tool calling for everything; losing the ability to constrain it means more turns where the model narrates instead of acting.

Token counting is approximate, and /v1/messages/count_tokens does not exist. Your context usage display is an estimate. When Claude Code's assumed window does not match reality, CLAUDE_CODE_MAX_CONTEXT_TOKENS lets you override the window it assumes for the active model, how it applies depends on how the model ID resolves, so read that doc rather than guessing.

MCP tool search is disabled by default when ANTHROPIC_BASE_URL points at a non-first-party host. If you run several MCP servers, their tools load differently than you are used to. Setting ENABLE_TOOL_SEARCH=true re-enables it, but only if your endpoint forwards tool_reference, Ollama's compatibility table does not list it, so assume it does not.

Also missing: the Batches API, citations, PDF document content blocks, metadata, and URL-based images (base64 images do work). Extended thinking is partially supported, budget_tokens is accepted but not enforced. The API key is accepted but never validated, which is fine locally and dangerous the moment you expose the port.

And then the model itself. This is the part no compatibility table captures. Claude Code's harness assumes a model that can hold a long plan, call tools precisely, and recover from a failed edit without restarting. Smaller open models are meaningfully worse at all three. In my testing the failure mode is rarely a crash, it is a session that takes four times as many turns, makes an edit against the wrong file, and needs supervision on every step. Subagents suffer worst, because a subagent's whole value is returning a good report from work you did not watch.

4. The Router Approach

The other route is a local gateway that speaks the Anthropic API on one side and whatever you like on the other. The best known is Claude Code Router (musistudio/claude-code-router).

Verified on 6 September 2026: the repository is active, not archived, last pushed 2 September 2026, with v3.0.22 released on 24 August 2026 and around 37,000 stars. So the answer to "is it abandoned" is no.

What has changed is its shape. Version 3 is no longer a small CLI proxy, it describes itself as a local control plane for coding agents generally, with a desktop app, provider presets, routing rules, fallbacks, credential pools and request logs. Claude Code is one of a dozen supported clients.

The CLI still exists and needs Node.js 22 or newer:

npm install -g @musistudio/claude-code-router
ccr ui

That opens a management UI on http://127.0.0.1:3458; the model gateway itself listens on http://127.0.0.1:3456. There is also a Docker path (docker compose up -d --build) documented in the repo. You add providers, start the server, then apply an agent profile for Claude Code.

Two honest notes. First, Ollama is not named anywhere in the current README, the listed providers are OpenAI, Anthropic, Gemini, OpenRouter, DeepSeek, SiliconFlow, Moonshot, Mistral, Z.AI, Bailian and custom compatible endpoints. You would add Ollama as a custom endpoint, and you should follow the project's own docs at ccrdesk.top rather than a config snippet from a blog, because that shape has changed between major versions.

Second, ask what the router buys you that Ollama's direct endpoint does not. If you want one local model, the answer is nothing, two environment variables are simpler and there is one less moving part. The router earns its place when you want routing: cheap local model for background tasks, a hosted model for the hard ones, automatic fallback when a provider is down, and one place to see what every request actually cost. That is a real problem, and it is an operations problem rather than a privacy one.

If you do run a router, treat it like any other service in your stack. It holds every provider credential you give it and it logs your prompts. The same rules apply as in security best practices for workflow automation: bind it to localhost, do not expose it, and know what it is storing.

5. When This Is Worth It

Privacy and data residency. This is the strongest case and the only one I find fully convincing. If the code cannot leave the building, client work under NDA, health or financial data, an air-gapped environment, then a local model is not a cost optimisation, it is the only option. Accept the capability drop as the price.

Offline. A train, a plane, a site with no reliable connection. A local model that answers slowly beats no model.

Learning. Running the whole loop yourself teaches you more about how the agent works in an afternoon than a month of using the hosted version. That is worth a weekend.

Cost, with an asterisk. People reach for this first and it is usually the weakest reason. If you already own a GPU that would otherwise sit idle, marginal cost is electricity. If you are buying hardware for this, the payback period is long enough that the model you bought it for will be obsolete first. And the honest accounting is per completed task, not per token: a session that needs four times the turns and your constant supervision is not cheap.

When it is not worth it: production work on a deadline, anything where a wrong edit costs real money, and multi-agent work. If you have read the subagents post, the whole point of delegation is trusting a report you did not watch being produced. That trust is exactly what a weaker model does not earn.

6. The Setup I Actually Recommend

For most people, the pragmatic answer is not either-or. It is Ollama for side tasks, hosted Claude for the agent loop.

Local models are genuinely good at bounded, high-volume, low-stakes work: classifying support emails, summarising a webhook payload, extracting fields from a document, generating embeddings. That work is repetitive, privacy-sensitive, and does not need frontier reasoning. Running it on your own box is a clear win.

So: keep Claude Code on the hosted models where its harness was designed to run, and give it an Ollama-backed service to call. In practice that means an n8n workflow or a small HTTP service hitting http://localhost:11434, which Claude Code reaches through a normal tool call or MCP server. Your agent stays sharp; your bulk inference stays on your hardware; the sensitive payloads never leave.

That is the shape of my own stack, and it sits alongside the self-hosted pieces in the n8n Docker Compose guide and getting started with n8n self-hosting. More on why I run things this way is on the about page.

One version note if you build that: Ollama's /api/embeddings endpoint is deprecated. Use /api/embed with input and read embeddings from the response.

---

If you want to try the local path properly, do it on a repository you would be happy to throw away, with git clean before you start, and give it a real task rather than a demo. You will know within an hour whether it is for you.

The free Claude Code for Builders course in the House of Loops classroom covers the hosted setup end to end, and there is an Ollama course in the same classroom for the local side.