# How to run Claude Code locally on a Mac, free and offline > Source: > Published: 2026-11-03 21:43:58+00:00 Claude Code can run on a local model on your own Mac. No API key, no cloud model, no usage limit. I built the open source piece that makes it work, called Claude Code Local, and this is the practical guide to setting it up. Here's the demo if you'd rather watch first: [https://www.youtube.com/watch?v=a9vtBSl_j_o](https://www.youtube.com/watch?v=a9vtBSl_j_o) Claude Code reads an environment variable called `ANTHROPIC_BASE_URL`, and Claude Code Local is a small Python server that answers there. It runs open AI models on your Mac's chip with Apple's MLX and replies in Anthropic's own Messages API format. Most local setups put a translator in the middle, because local servers usually speak OpenAI's format. This one speaks Claude Code's language directly, so there's nothing in between. The server also turns each model's own tool call format (Gemma 4, Qwen, Llama JSON) into Claude Code tool calls, repairs garbled tool JSON, and reuses the prompt cache between turns so long sessions don't re-read everything. That's what lets file edits, commands and tools work the same way they do with Claude. It's MIT licensed and v1.0.0 just shipped. A Mac with Apple Silicon (M1 or newer). Python 3.12, which setup installs for you. Claude Code, which the installer adds if it's missing. You don't have to pick. Setup looks at your Mac's memory and chooses a model that fits: | Your Mac's memory | The model you get | |---|---| | Under 16 GB (8 GB) | Qwen 3.5 2B, 8-bit, reads images, 16K context, server peaks at 4.2 GB | | 16 GB (MacBook Air, base models) | Qwen 3.5 4B, bf16, reads images, 16K context, server peaks at 10.6 GB | | 32 to 63 GB (Pro) | Gemma 4 12B | | 64 to 95 GB (Max) | Gemma 4 31B | | 96 GB and up (Max, Ultra) | Qwen 3.8 27B, 8-bit | On the small Macs, the speeds we measured on an M4 Pro were 22 tokens a second for the 4B model and 92 for the 2B. Both passed our Claude Code test: read a file, fix a bug with Edit, run a script, describe an image. The full numbers and settings are in [docs/SMALL-MACS.md](https://github.com/nicedreamzapp/claude-code-local/blob/main/docs/SMALL-MACS.md). On the big end, Qwen 3.8 27B passed our Claude Code test (write a file, run it, report) in 38 seconds. We also score models on our open [Agent-12 leaderboard](https://nicedreamzapp.github.io/agent12/), where it got 12/12 easy and 7/8 hard. Those scores come from Agent-12's own harness, not from inside Claude Code, and Claude Code sends the model a lot more per turn. A local model is not Claude Opus, and I won't pretend it is. Big models on a 64 GB or 96 GB Mac handle real multi step work. On 8 or 16 GB, keep requests to one clear step at a time. ``` curl -fsSL https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/install.sh | bash ``` If you'd rather read the script first: ``` git clone https://github.com/nicedreamzapp/claude-code-local cd claude-code-local bash setup.sh ``` Setup picks your model, downloads it, installs the server, and puts `Claude Local.command` on your Desktop. Double click it and you're coding on your own machine. If you get asked to sign in to a Claude account, your `claude` is too old. Update it with `curl -fsSL https://claude.ai/install.sh | bash`. Doing it by hand comes down to this. Start the server, then launch Claude Code against it: ``` ANTHROPIC_BASE_URL=http://localhost:4000 \ ANTHROPIC_API_KEY=sk-local \ claude --model claude-sonnet-4-6 ``` The key is just `sk-local`. The server never checks it. Say Claude Code says "5-hour limit reached" or "You've reached your weekly limit", or your API key comes back with "credit balance is too low", and the reset is hours away. Type `exit` in Claude Code, then type `keep going`. You get a short menu, and the same conversation carries on with whichever model you pick. The options are the models on your machine, sized to your memory, or free cloud models from OpenRouter if you add a free key: ``` mkdir -p ~/.config/claude-code-local echo 'OPENROUTER_API_KEY=your-free-key' >> ~/.config/claude-code-local/keepgoing.env ``` The cloud key is optional. Free cloud models can get busy later in the day, and the models on your Mac are always there. When your limit resets, just run plain `claude` again. The install never changes it, so it still uses your Claude plan. You can also make the switch automatic. Add one hook to Claude Code and the moment you hit your limit, a new window opens in the same folder and carries on without a menu. Setup is in [docs/AUTO-HANDOFF.md](https://github.com/nicedreamzapp/claude-code-local/blob/main/docs/AUTO-HANDOFF.md). Off a Mac there's no MLX, so the model runs on llama.cpp instead. The installer looks at your hardware (NVIDIA, AMD, or just your CPU), grabs a pinned llama.cpp build, and picks a vision model that fits. A 24 GB NVIDIA card gets Qwen 3.5 9B at full BF16, for example. Linux uses the same one liner as the Mac. On Windows, in PowerShell: ``` irm https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/install.ps1 | iex ``` You need git, Python 3 and Claude Code installed. Then run `claude-local` on Linux, or double click Claude Local on your Windows Desktop. `keep going` works there too. Your code never leaves your Mac. No cloud model, no tracking, no analytics. Claude Code itself makes some background calls to Anthropic, so the launchers switch them off with Anthropic's documented settings: ``` CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 DISABLE_AUTOUPDATER=1 CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL=1 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 ``` You can check it yourself. During a session, run: ``` lsof -a -i -p "$(pgrep -d, -f claude)" ``` That lists the network connections of every Claude process, and the only one is `localhost:4000`. Because the model runs on your machine, an Anthropic outage doesn't stop it either. The one exception is your own choice. If you pick a free cloud model in `keep going`, that conversation goes to OpenRouter. The repo: [https://github.com/nicedreamzapp/claude-code-local](https://github.com/nicedreamzapp/claude-code-local) How to guides and docs: [https://nicedreamzapp.github.io/claude-code-local/](https://nicedreamzapp.github.io/claude-code-local/) The demo: [https://www.youtube.com/watch?v=a9vtBSl_j_o](https://www.youtube.com/watch?v=a9vtBSl_j_o) If you run it on an 8 GB or 16 GB Mac, tell us how it goes in [issue #57](https://github.com/nicedreamzapp/claude-code-local/issues/57). I especially want to hear from people on older or smaller Macs about which models really fit.