Free Claude Code - Setup Guide

Use Claude Code in your terminal for free by routing requests through open-source AI providers instead of paying Anthropic's API.

What is this?

Free Claude Code is an open-source proxy that sits between Claude Code (Anthropic's CLI coding tool) and any AI provider you choose. Instead of your requests hitting Anthropic's paid API, the proxy redirects them to free or cheaper providers like NVIDIA NIM, Kimi, DeepSeek, OpenRouter, Ollama, and more.

You still get the full Claude Code experience, the same CLI, the same VS Code extension, the same tool use and streaming, but the AI responses come from whichever provider you configure. Zero API costs if you pick a free provider.

What it supports

• 11 provider backends (NVIDIA NIM, Kimi, Wafer, OpenRouter, DeepSeek, LM Studio, llama.cpp, Ollama, OpenCode Zen, OpenCode Go, Z.ai)
• Per-model routing, send Opus, Sonnet, and Haiku requests to different providers
• A local Admin UI to configure everything from your browser
• Works with Claude Code CLI, VS Code extension, and JetBrains
• Optional Discord/Telegram bots and voice note support

Prerequisites

All you need is a computer with a terminal:

• macOS, Terminal (built-in)
• Windows, PowerShell (built-in)
• Linux, any terminal

The install script automatically handles Python, Claude Code, and all dependencies. You don't need to install anything manually.

Step 1, Run the install script

Open your terminal and paste the command for your operating system.

macOS / Linux

curl -fsSL "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh?raw=1" | sh

Windows PowerShell

irm "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.ps1?raw=1" | iex

This single command installs everything: Python 3.14, uv (package manager), Claude Code CLI, and the Free Claude Code proxy. It also creates two shortcut commands, fcc-server and fcc-claude, that you'll use in the next steps.

Step 2, Start the proxy server

fcc-server

You'll see output like this:

INFO:     Admin UI: http://127.0.0.1:8082/admin (local-only)

This means the proxy is running. Keep this terminal window open, the proxy needs to stay active while you use Claude Code. The Admin UI link is where you'll configure your AI provider in the next step.

Step 3, Get a free API key (NVIDIA NIM)

The fastest way to get started is with NVIDIA NIM, which has a generous free tier.

1. Go to build.nvidia.com/settings/api-keys
2. Create an account (free) and generate an API key
3. Copy the key

Step 4, Configure the provider in the Admin UI

1. Open the Admin UI link from your terminal (usually http://127.0.0.1:8082/admin)
2. Find the NVIDIA_NIM_API_KEY field
3. Paste your API key
4. Click Validate to test the connection
5. Click Apply to save

The default model (nvidia_nim/nvidia/nemotron-3-super-120b-a12b) is already configured. You can change it later from the same page.

Step 5, Launch Claude Code

Open a new terminal window (keep fcc-server running in the first one) and run:

fcc-claude

That's it. Claude Code is now running through the free proxy. Start asking it to build, debug, or write code, no API bill.

All supported providers

You can switch providers any time by changing the API key and model in the Admin UI. No reinstall needed.

Local providers (no API key needed)

If you want everything running on your own machine with zero external calls, use Ollama, LM Studio, or llama.cpp. These run the AI model directly on your hardware. Example with Ollama:

# Install and start Ollama
ollama pull llama3.1
ollama serve

Then in the Admin UI, set the model to ollama/llama3.1.

Mix providers by model tier

One of the most powerful features. In the Admin UI, you can route different Claude model tiers to different providers:

Leave any tier blank to fall back to the default MODEL. This lets you use a powerful cloud model for complex tasks and a fast local model for simple ones.

VS Code extension setup

If you use Claude Code inside VS Code instead of (or in addition to) the terminal:

1. Open VS Code Settings (Cmd+, on Mac, Ctrl+, on Windows/Linux)
2. Search for claude-code.environmentVariables
3. Click Edit in settings.json
4. Add this block:

"claudeCode.environmentVariables": [
  { "name": "ANTHROPIC_BASE_URL", "value": "http://localhost:8082" },
  { "name": "ANTHROPIC_AUTH_TOKEN", "value": "freecc" },
  { "name": "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY", "value": "1" },
  { "name": "CLAUDE_CODE_AUTO_COMPACT_WINDOW", "value": "190000" }
]

1. Reload the VS Code window.

Make sure fcc-server is running before you start using it.

JetBrains setup

For IntelliJ, WebStorm, PyCharm, or any JetBrains IDE with Claude ACP:

1. Open the ACP config file:
   • Windows: C:\Users\%USERNAME%\AppData\Roaming\JetBrains\acp-agents\installed.json
   • macOS/Linux: ~/.jetbrains/acp.json
2. Add the env block under acp.registry.claude-acp:

"env": {
  "ANTHROPIC_BASE_URL": "http://localhost:8082",
  "ANTHROPIC_AUTH_TOKEN": "freecc",
  "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
  "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "190000"
}

1. Restart the IDE.

Troubleshooting

"command not found" after install

Close your terminal completely and reopen it. The install script adds commands to your PATH, but the current terminal session doesn't pick them up until restarted.

Claude Code shows a login/auth screen

Make sure fcc-server is running first, then launch with fcc-claude (not plain claude). The fcc-claude wrapper sets the right environment variables automatically.

Provider errors or timeouts

Open the Admin UI and double-check your API key. Click Validate to test the connection. If it fails, the key might be expired or the provider might be down, try a different one.

Slow responses

Try a different provider or a smaller model. Local models (Ollama, LM Studio) depend entirely on your hardware, you need a decent GPU for good performance.

Want to update to the latest version?

Run the install script again. It will update everything in place.

Quick reference

Links

• GitHub repo: github.com/Alishahryar1/free-claude-code
• NVIDIA NIM keys: build.nvidia.com/settings/api-keys