How to Run Claude Code with Ollama: Direct Local Setup and Checks

You can connect Claude Code to Ollama without making a translation proxy the default part of your setup. Ollama documents an Anthropic-compatible API and a launcher for Claude Code. The useful first goal is a small session against a local model, with a clear understanding of which endpoint and model you selected.

This tutorial follows that direct route. It also shows a manual configuration for Bash or WSL, a tiny JavaScript task, and the checks to make before using the setup with private code. Model quality and tool support still matter: connecting successfully does not make a local model equivalent to a hosted Claude model.

What changed: the proxy is optional

Older integration guides put LiteLLM or another router between Claude Code and Ollama. The premise that this is always necessary is now outdated. Ollama supports a subset of the Anthropic Messages API and documents a direct Claude Code integration. See the official integration guide and API compatibility reference.

A proxy may still be useful when you deliberately need routing, centralized controls, or a gateway used by several tools. That is a separate architecture decision. It is not a prerequisite for the direct connection described here, and this walkthrough does not rely on an alias pretending that a local model is a particular hosted Claude release.

Step 1: Check the tools and select a local model

Install or update Ollama using its official download instructions. Install Claude Code using the current setup documentation; the native installer is the recommended route there. Use the instructions for your operating system rather than assuming every machine needs npm and Node.js for Claude Code itself.

In your terminal, check the installed versions and local model inventory:

ollama --version
claude --version
ollama list

Choose a model that supports tool use and fits your hardware with room for context. The Qwen3-Coder model page documents a local model and a Claude Code launch example. The commands below use qwen3-coder as an example, not a claim that it fits every laptop or is the best model for every task:

ollama pull qwen3-coder
ollama list

Downloading a model consumes disk space and network bandwidth. Its runtime memory needs also depend on context and execution settings. Check the model’s current size and your available resources before pulling it; choose a smaller compatible model if necessary and substitute its exact name consistently in the following commands.

A model served through Ollama is not automatically local inference. Ollama also supports cloud models. For this walkthrough, select a downloaded local model, not a cloud model.

Step 2: Allow enough context

Coding agents need space for instructions, source files, tool descriptions, and tool results. Ollama’s context-length guide recommends at least 64,000 tokens for tasks such as agents and coding tools. Increasing context increases memory requirements, so first confirm that your selected model and hardware can support it.

The Ollama app provides a context-length setting. For a manually managed server, the documented CLI form is:

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

That command starts a server with the setting; it does not reconfigure an Ollama instance already running as an app or service. Do not start a second server on the same port. Use the appropriate configuration method for the instance you actually run, then restart it if the change requires that.

During an active session, inspect the loaded model:

ollama ps

Check the allocated context and processor information. If the model cannot run with the required context at usable speed, reduce the task size or choose a different model or machine. Avoid treating a large advertised context maximum as proof that your current server allocated that much memory.

Step 3: Launch the direct integration

Start with a scratch project rather than your main repository. Ollama’s documented entry point is:

ollama launch claude

Follow the selector and confirm the intended model. For the example model above, its official library page also shows:

ollama launch claude --model qwen3-coder

If your installed Ollama does not recognize the launcher, check its version and update instructions. Do not add a proxy merely to work around an outdated launcher without first checking the documented manual route.

For readers new to the agent itself, our Claude Code tutorial explains the ordinary project workflow.

Manual setup for Bash and WSL

Ollama also documents setting the Anthropic endpoint and authentication variables explicitly. The following Bash/WSL command applies them to this one invocation:

ANTHROPIC_AUTH_TOKEN=ollama \
ANTHROPIC_API_KEY="" \
ANTHROPIC_BASE_URL=http://localhost:11434 \
claude --model qwen3-coder

Here, ollama is the local placeholder token and the API-key variable is empty. It is not an Anthropic credential. The endpoint points directly to Ollama’s local server rather than the old tutorial’s proxy on port 4000. See the manual setup for current instructions.

The multiline syntax above is for Bash, including a WSL shell, not native PowerShell. If you work in PowerShell, use the launcher or the official platform-specific instructions rather than pasting Bash variable assignments unchanged.

Existing Claude Code settings can affect the endpoint and credentials. Run /status and inspect the effective configuration before you submit project content. If a saved setting overrides the intended endpoint, correct that setting first; defining a shell variable is not sufficient evidence that the selected route changed.

Step 4: Test one small local change

A useful first task should exercise file reading, an edit, and a test without requiring access to external services. In an empty scratch directory, create label.cjs:

function label(value) {
  return value.trim();
}

module.exports = { label };

Create label.test.cjs:

const test = require('node:test');
const assert = require('node:assert/strict');
const { label } = require('./label.cjs');

test('trims text', () => {
  assert.equal(label(' hello '), 'hello');
});

test('preserves an empty label', () => {
  assert.equal(label(''), '');
});

test('treats a missing value as empty', () => {
  assert.equal(label(null), '');
});

This exercise uses Node.js for the local test, independently of how Claude Code was installed. Run:

node --test label.test.cjs

The null-input case should fail. Launch the integration from that directory and ask:

Read label.cjs and label.test.cjs. Explain the failing null-input case, make the smallest change to label.cjs that handles null and undefined as an empty label, and run the tests. Do not change the tests or install dependencies.

Keep the ordinary permission checks enabled and review any requested command. A possible minimal implementation is return (value ?? '').trim();. The goal is not to obtain that exact formatting: it is to see whether the selected model can use tools, make a bounded edit, and report the real test result.

After the agent finishes, inspect the file and run the tests yourself. A text response saying “all tests pass” is not a substitute for the output of the local command. This example is a reproducible exercise, not a benchmark or a claim that a particular model session was tested for this article.

Troubleshoot the connection before changing the architecture

Connection refused: confirm that Ollama is running and that the configured host is reachable. A basic inventory request is:

curl http://localhost:11434/api/tags

In WSL or a container, localhost must reach the Ollama instance you intend to use. If the server runs in another environment, resolve that networking arrangement before changing model settings.

Model not found: compare the selected name with ollama list. Use the exact downloaded tag instead of a hosted Claude identifier copied from an old proxy example.

Text answers but broken tool calls: check model support and the compatibility reference. Ollama implements a subset of the API; an available connection does not prove every tool or advanced feature works with every model.

Slow or unstable sessions: inspect ollama ps, allocated context, and memory pressure. Try a smaller task before changing several settings at once. Repeated agent loops can magnify a modest per-request delay.

Local inference and privacy are separate checks

Selecting a downloaded model and routing inference to a local Ollama server is different from proving that the entire toolchain makes no external requests. Cloud models, web tools, MCP servers, plugins, telemetry, and commands run by the agent need their own review.

Ollama documents disabling its cloud features with disable_ollama_cloud in its server configuration or OLLAMA_NO_CLOUD=1, followed by a restart. Apply the setting to the actual Ollama server, not merely the shell launching Claude Code. Check the Ollama FAQ and Claude Code’s data-usage documentation against your requirements.

Do not put secrets in the scratch project. For proprietary code, follow your organization’s rules and inspect the complete configuration. This tutorial does not promise an air-gapped setup, zero retention for every component, or that a localhost endpoint alone prevents all network traffic.

Frequently Asked Questions