Running Claude Code via NVIDIA NIM Proxy

free-cc.md

This guide walks you through routing Claude Code to NVIDIA NIM using a local proxy server.

Prerequisites

Before starting, ensure you have uv installed on your system to manage Python tools.

---

Step 1: Get an NVIDIA NIM API Key

1. Visit the NVIDIA API Keys settings page.
2. Generate a new API key and save it securely. You will need this to authenticate with the NIM models.

Step 2: Install and Start the Proxy Server

Install the proxy tool using uv and launch the server.

# Install the free-claude-code proxy
uv tool install --force git+https://github.com/Alishahryar1/free-claude-code.git

# Launch the proxy server
fcc-server

Note: Keep this terminal window open. The server runs on port 8082. You can access the admin panel at http://127.0.0.1:8082/admin.

Step 3: Configure Environment Variables

Open a new terminal window. You must set these environment variables to intercept Claude Code traffic and route it to your local server.

# Set the dummy authentication token
export ANTHROPIC_AUTH_TOKEN="freecc"

# Redirect the base URL to your local proxy
export ANTHROPIC_BASE_URL="http://localhost:8082"

See the comment below on how you can add this to your .bashrc as a custom function

Step 4: Launch and Verify Claude Code

In the same terminal where you just configured the environment variables, launch Claude Code.

# Start Claude Code
claude

Once inside the Claude Code interface, verify that the routing is working properly by running the status command:

/status

Ram N

---

Reference Links

• Free Claude Code Model Picker Documentation
• NVIDIA NIM Setup

Fix for Python 3.14 segfault / compatibility on macOS (Python 3.13)

uv python install 3.14 currently installs 3.14.0a6 (alpha), which segfaults on fcc-server. Python 3.14 final isn't available through uv yet. Here's how to get it working on Python 3.13:

1. Clone the repo locally

git clone https://github.com/Alishahryar1/free-claude-code.git
cd free-claude-code

2. Relax the Python version requirement

In pyproject.toml, change:

requires-python = ">=3.14"

to:

requires-python = ">=3.13"

3. Fix Python 3.14-only except syntax (8 occurrences)

Python 3.14 allows except X, Y: but 3.13 requires except (X, Y):. Fix these files:

• providers/openai_compat.py:459
• messaging/platforms/discord.py:404, 477
• core/anthropic/tokens.py:103
• messaging/rendering/telegram_markdown.py:179, 186
• messaging/rendering/discord_markdown.py:171, 178

e.g. except asyncio.CancelledError, GeneratorExit: → except (asyncio.CancelledError, GeneratorExit):

4. Add from __future__ import annotations to all source files

Python 3.14 has deferred annotation evaluation by default (PEP 649). Without it on 3.13, you get NameError for forward references like -> Settings inside the Settings class, and ClassVar[GlobalRateLimiter | None] inside GlobalRateLimiter.

Run this to patch all source files:

python3 -c "
import os
SOURCE_DIRS = ['api', 'cli', 'config', 'core', 'messaging', 'providers']
for d in SOURCE_DIRS:
    for root, dirs, files in os.walk(d):
        dirs[:] = [x for x in dirs if x != '__pycache__']
        for f in files:
            if not f.endswith('.py'): continue
            path = os.path.join(root, f)
            content = open(path).read()
            if 'from __future__ import annotations' in content: continue
            lines = content.split('\n')
            insert_at = 0
            if lines and lines[0].strip().startswith('\"\"\"'):
                if lines[0].strip().count('\"\"\"') >= 2:
                    insert_at = 1
                else:
                    for i in range(1, len(lines)):
                        if '\"\"\"' in lines[i]:
                            insert_at = i + 1
                            break
            lines.insert(insert_at, '')
            lines.insert(insert_at + 1, 'from __future__ import annotations')
            lines.insert(insert_at + 2, '')
            open(path, 'w').write('\n'.join(lines))
print('Done')
"

5. Install with Python 3.13

uv tool install --force --python 3.13 /path/to/free-claude-code

6. Configure your .env

Create a .env in your working directory:

NVIDIA_NIM_API_KEY="nvapi-your-key-here"
MODEL="nvidia_nim/nvidia/nemotron-3-super-120b-a12b"
MODEL_OPUS="nvidia_nim/mistralai/mistral-large-3-675b-instruct-2512"
MODEL_SONNET="nvidia_nim/qwen/qwen3-coder-480b-a35b-instruct"
MODEL_HAIKU="nvidia_nim/deepseek-ai/deepseek-v4-pro"
ANTHROPIC_AUTH_TOKEN="freecc"
ENABLE_MODEL_THINKING=true
MESSAGING_PLATFORM="none"
VOICE_NOTE_ENABLED=false
FCC_OPEN_BROWSER=false

7. Important: export .env before starting the server

Pydantic-settings doesn't load validation_alias fields (MODEL_OPUS, MODEL_SONNET, MODEL_HAIKU) from .env files — only from actual environment variables. You must export them:

cd ~/your-project-dir
set -a && source .env && set +a && fcc-server

Without set -a && source .env && set +a, only the MODEL (default/fallback) will be loaded; the per-model overrides (Opus, Sonnet, Haiku) will be ignored.

8. Optional: clean up the model list in Claude Code's /model picker

By default the proxy lists ALL ~97 NIM models. To show only your configured models, edit api/routes.py and remove the block at ~lines 145-152 that calls provider_registry.cached_prefixed_model_infos(). After the patch, only your MODEL/MODEL_OPUS/MODEL_SONNET/MODEL_HAIKU + Claude aliases will appear.

To add extra models (e.g. Kimi, GLM) without listing all 97, add import os at the top of api/routes.py and insert this after the configured models loop:

    extra_models = os.environ.get("FCC_EXTRA_MODELS", "").strip()
    if extra_models:
        for extra in extra_models.split(","):
            extra = extra.strip()
            if extra:
                _append_provider_model_variants(models, seen, extra)

Then in your .env:

FCC_EXTRA_MODELS="nvidia_nim/moonshotai/kimi-k2.6,nvidia_nim/z-ai/glm-5.1"

Reinstall after patching: uv tool install --force --reinstall --python 3.13 /path/to/free-claude-code

---

Tested on macOS ARM (Apple Silicon), Python 3.13.11, uv, May 2026.

Here's a nice custom function to add to your .bashrc to turn it on or off.

# Function to point Anthropic traffic to your local proxy
anthropic_proxy_on() {
    export ANTHROPIC_AUTH_TOKEN="freecc"
    export ANTHROPIC_BASE_URL="http://localhost:8082"
    echo "🤖 Anthropic proxy enabled (Localhost:8082)"
}

# Function to clear it and go back to normal
anthropic_proxy_off() {
    unset ANTHROPIC_AUTH_TOKEN
    unset ANTHROPIC_BASE_URL
    echo "🌐 Anthropic proxy disabled (Default routing)"
}