Run Claude Code on Ollama
Ollama serves two APIs: an OpenAI-compatible one at /v1, and — since v0.14.0 — a subset of the Anthropic Messages API, which is what Claude Code speaks. So you can point Claude Code straight at http://127.0.0.1:11434 by exporting two environment variables. Magpie is the route that skips them: it listens on http://127.0.0.1:3425/v1, so switching Claude Code to Ollama is one command, no key, no environment variables to export and no config file to hand-edit. This page is the whole path, from ollama pull to switching back to a cloud model.
Claude Code on Ollama, in four commands
ollama pull qwen3-coder:30b # any tool-calling model you like
magpie provider add ollama # local preset — no key, no URL
magpie provider test ollama # one tiny request, with latency
magpie claude ollama/qwen3-coder:30b # point Claude Code at it
The model name is whatever ollama list shows, in provider/model form. Nothing is written into your shell environment.
Why run Claude Code locally
Three reasons people do it, in the order they usually matter:
- Cost. A local model has no per-token bill. For long refactors where the agent reads a lot and writes little, the difference is the whole bill.
- Nothing leaves the machine. No prompt, no file path and no diff goes to a vendor. That is the only way some repositories can be touched by an agent at all.
- No rate limit and no card. A local server does not 429 you halfway through a run.
What you give up is quality per token. A 30B local model is not a frontier model: it will make a wrong edit more often, and the agent loop turns one wrong edit into three. The honest use is narrow, repetitive work — renames, test scaffolding, boilerplate ports — while you keep a cloud model for anything where a bad assumption is expensive.
Install Ollama and pull a model
Install Ollama from ollama.com and confirm the server is up before involving Magpie. Its default address is http://127.0.0.1:11434, and Ollama serves an OpenAI-compatible API at /v1.
ollama --version # the CLI is on your PATH
ollama list # what you already have
ollama pull qwen3-coder:30b # a coding-tuned model with tool calling
ollama run qwen3-coder:30b # sanity check: it answers at all
Pull the model you actually intend to use, not the biggest one that fits. A model that spills out of memory is offloaded to the CPU and still runs — it just answers each turn slowly enough that an agent session becomes unusable, and the first sign is usually a timeout rather than an error.
Add Ollama to Magpie
Ollama sits in Magpie's local group of presets, alongside LM Studio. Local presets need no key, because there is nothing to authenticate against — the server is on your machine.
magpie presets # vendors, relays and local servers, grouped
magpie provider add ollama # local — no key, no url=
magpie providers # every provider: host, key, models, users
magpie provider ollama # this one in detail
magpie provider models ollama # re-fetch the list Ollama serves
magpie provider test ollama # one small request per API, with latency
Run magpie provider test ollama before you go further. It fires one small request and reports the latency, which separates two failures that otherwise look identical inside Claude Code: "the gateway cannot reach Ollama" and "Ollama is up but the model is not loaded yet".
If your Ollama is not on the default port — in a container, behind a tunnel, on another machine — add it as a custom provider instead, with url= pointing at the OpenAI-compatible base:
magpie provider add "Ollama Remote" url=http://192.168.1.20:11434/v1 models=qwen3-coder:30b
Every preset accepts the same overrides, so a moved endpoint never means dropping back to a fully custom provider. The flags and what each one does are on the config page.
Point Claude Code at the model
One command, and the model name is provider/model — the same shape Magpie uses for every vendor.
magpie claude ollama/qwen3-coder:30b # Claude Code → the local model
magpie models # the catalog your agents can see
Under the hood Magpie edits ~/.claude/settings.json — only the keys it needs to: the provider, the model, and the opus/sonnet/haiku/fable mappings. Comments, key order and indentation in that file survive, and writes are atomic. You do not relaunch Claude Code: the next request it makes goes through the gateway at http://127.0.0.1:3425/v1, which translates Anthropic-shaped requests into the OpenAI-shaped ones Ollama understands.
To confirm it took, ask the agent to identify itself, or run magpie providers and look at which agents are listed against ollama.
magpie provider test ollama proves the second; magpie providers shows the first. When a session hangs, knowing which of the two failed is most of the diagnosis.
Which local models are usable
The gateway translates the API, but it cannot add a capability the model does not have. Claude Code edits files and runs commands by emitting tool calls, so the model needs a tool-calling template — a chat model without one will reply with prose where Claude Code expects a call, and the agent will look like it is ignoring you.
| What you need | Why it decides the outcome |
|---|---|
| Tool calling | Without it the agent cannot edit a file or run a command, whatever the model's benchmark scores say. |
| Context window | An agent turn carries the file, the diff and the history. A short window truncates mid-task, which reads as "the model forgot what I asked". |
| Coding tuning | A coding-tuned model of the same size is markedly better at precise edits than a general chat model. |
| Fits in memory | The one that offloads to CPU answers, but too slowly to keep an agent session alive. |
Check the model's own card for tool-calling support rather than trusting a family name; the same family ships variants that do and do not. Model names and tags change often enough that this page does not pin a list.
LM Studio instead of Ollama
LM Studio is the other local preset, and it takes the same treatment. Start its local server, then:
magpie provider add lmstudio # local preset, no key
magpie provider test lmstudio
magpie claude lmstudio/qwen3-coder-30b # same provider/model shape
LM Studio's built-in server is OpenAI-compatible too, so the only thing that changes is the provider id and where the server listens. Its default port is 1234 rather than Ollama's 11434 — if you moved it, add LM Studio as a custom provider with url= pointing at http://127.0.0.1:<port>/v1.
Which of the two to pick is mostly about the models you already have downloaded and whether you want a GUI for loading them. Both end up as one provider in Magpie, and you can have both at once.
Switching back to a cloud model
Nothing about going local is one-way. The same command with a cloud provider and model puts Claude Code back:
magpie providers # what is configured: vendors, relays, local
magpie claude deepseek/deepseek-flash # back to a cloud model, one command
magpie claude anthropic/claude-sonnet-5-5 # or a subscription you already pay for
If you switch back and forth by context rather than by mood, use profiles instead of typing commands: in the TUI, s saves a profile and p opens the list. One profile with Ollama and one with a cloud provider means moving every agent in one keypress, and it is reversible without remembering what the settings used to say.
Two things stay where they are when you switch: Magpie's own state in ~/.config/magpie/providers.json, and any per-model prices you set with magpie model price. A local model costs nothing per token, but if you want the usage ledger to stay honest about a relay's pricing later, that is where it comes from — see telling Magpie what a model costs.
When it does not work
magpie claude ollama/<model>.
magpie provider test ollama shows the latency of a single request, which is the fastest way to see this before Claude Code does.
- Provider shows as unauthenticated. Local presets take no key, so this is almost always a different provider. Note that Magpie ignores
ANTHROPIC_API_KEYandOPENAI_API_KEYfrom your shell by design — keys live in Magpie, not in your environment. - Ollama is running but the model list is empty. Run
ollama listin a terminal. If the model is missing there, Magpie has nothing to fetch; pull it first, thenmagpie provider models ollama. - Port already in use. Something else holds
11434or3425. Move the server, then add it as a custom provider withurl=rather than fighting the port. - Claude Code still talks to a cloud model. Check
~/.claude/settings.json— the provider and model keys are what Magpie rewrites. If a wrapper script or an exported base URL is overriding them, remove it: the agent should point athttp://127.0.0.1:3425/v1and nothing else.
For the gateway side in more depth — API translation, which endpoints it speaks, failover across keys — the config page covers it. For why a local gateway is worth running at all compared with a desktop switcher, see Magpie vs cc-switch.
Frequently asked
Does Claude Code work with Ollama?
Yes. Ollama supports a subset of the Anthropic Messages API since v0.14.0, so Claude Code can talk to it directly at http://127.0.0.1:11434 once ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN are set. Magpie does the same job without environment variables: Claude Code points at the gateway on 127.0.0.1:3425 and Magpie forwards the request to Ollama. Either way the model has to support tool calling, because that is what Claude Code uses to edit files and run commands.
Do I need an API key to use Ollama with Magpie?
No. Ollama and LM Studio are in Magpie's local group of presets, so magpie provider add ollama takes no key. Magpie never reads API keys from your shell environment, so there is nothing to export either.
How much memory does a local model need for Claude Code?
Roughly 0.6 GB of memory per billion parameters at 4-bit quantization, so a 30B model needs about 18 to 20 GB of unified or video memory and a 7B model about 4 to 5 GB. Coding agents also hold a long context, which adds to that. A model that does not fit gets offloaded to the CPU and becomes too slow to drive an agent.
Why does the local model stop calling tools inside Claude Code?
Tool calling is a property of the model, not of the gateway. A model without a tool-calling template will return plain text where Claude Code expects a tool call, so the agent looks stuck or asks you to do things yourself. Check the model's own card for tool-calling support, and prefer a coding-tuned model over a general chat one.
Will switching to Ollama change my Claude Code settings file?
Magpie edits ~/.claude/settings.json surgically: only the keys it needs to change are touched, and comments, key ordering and indentation survive. Your provider and model names are what change. Running magpie claude <provider>/<model> with a cloud provider puts them back.
Can I keep Claude Code on a cloud model and only use Ollama for some projects?
Yes. Magpie supports profiles: in the TUI, s saves a profile and p opens the list, so switching a profile puts every agent back the way that profile had it. A profile with Ollama and a profile with a cloud provider let you move a whole setup in one keypress.