How to Set Up Claude Code with FreeLLMAPI: Complete Configuration Guide

You can run Claude Code against FreeLLMAPI by pointing it at your local proxy server and supplying your unified API key via the ANTHROPIC_AUTH_TOKEN environment variable.

FreeLLMAPI provides an OpenAI-compatible proxy that also implements Anthropic's Messages API, making it possible to use Claude Code — Anthropic's official CLI client — without any code changes. This guide walks through the complete setup process using the actual commands and configuration options from the tashfeenahmed/freellmapi repository.

Prerequisites and Installation

Before configuring Claude Code, you need a running FreeLLMAPI server and a valid unified API key.

Install the FreeLLMAPI CLI globally:

npm i -g freellmapi

Start the proxy server on the default port:

freellmapi start

The server exposes a base URL at http://localhost:3001/v1 according to docs/api.md lines 7-9. This router translates both OpenAI-style and Anthropic-style requests to the appropriate backend model pool.

Obtaining Your Unified API Key

FreeLLMAPI uses a single unified key for all authentication. Retrieve this key from the dashboard's Keys page. You can transmit this key either as:

• An x-api-key header
• A Bearer token in the Authorization header

This flexibility is documented in docs/api.md lines 7-9 and 323-329.

Configuring Claude Code with the Setup Command

FreeLLMAPI ships with a convenience command that automates Claude Code configuration. The setup-claude command writes a temporary configuration while backing up any existing files, as implemented in cli/src/tools.ts and documented in README.md lines 137-152.

Run the one-line setup:

npx freellmapi setup-claude \
  --url http://localhost:3001 \
  --api-key <YOUR_UNIFIED_KEY>

Critical environment variable requirement: Claude must receive your token via ANTHROPIC_AUTH_TOKEN formatted as a Bearer token. Supplying ANTHROPIC_API_KEY instead will cause Claude Code to abort, as it interprets that variable as a conflicting first-party credential. This behavior is explicitly documented in docs/api.md lines 341-357.

Launching Claude Code

After configuration, start Claude Code using the provided launcher:

npx freellmapi launch

This command internally runs Claude Code with ANTHROPIC_AUTH_TOKEN properly injected, avoiding any pollution of your global configuration files. Alternatively, you can run Claude Code directly after exporting the token manually.

Claude Code automatically appends /v1/messages when you set the origin to the FreeLLMAPI server's root (e.g., http://localhost:3001), as noted in docs/api.md lines 325-329.

Model Mapping and Endpoint Compatibility

In the dashboard's Keys → Anthropic tab, map each Claude family to your preferred backend:

Claude Family	Mapping Options
default	auto selection or specific model pin
opus	Router-selected or pinned model
sonnet	Router-selected or pinned model
haiku	Router-selected or pinned model

The proxy implements Anthropic-specific endpoints including POST /v1/messages/count_tokens and a content-negotiated GET /v1/models, as documented in docs/api.md lines 339-341.

Verify connectivity with a quick curl test:

curl -H "Authorization: Bearer <YOUR_UNIFIED_KEY>" \
     http://localhost:3001/v1/models

Complete Setup Script

For automation or documentation purposes, here is the full sequence:

# Install FreeLLMAPI

npm i -g freellmapi

# Start proxy in background

freellmapi start &

# Configure Claude Code (one-time)

npx freellmapi setup-claude \
  --url http://localhost:3001 \
  --api-key sk-freellm-xxxxxxxx

# Launch with credentials injected

npx freellmapi launch

Summary

• FreeLLMAPI exposes an Anthropic-compatible Messages API at your local server root
• Use npx freellmapi setup-claude for automated, non-destructive configuration
• Export the unified key as ANTHROPIC_AUTH_TOKEN, never ANTHROPIC_API_KEY
• Run npx freellmapi launch to start Claude Code with proper authentication
• Map Claude model families (default, opus, sonnet, haiku) in the dashboard's Keys → Anthropic tab

Frequently Asked Questions

Why does Claude Code fail when I set ANTHROPIC_API_KEY?

Claude Code interprets ANTHROPIC_API_KEY as a first-party Anthropic credential and aborts when it conflicts with a custom origin. The FreeLLMAPI integration expects ANTHROPIC_AUTH_TOKEN instead, which Claude Code treats as a generic Bearer token compatible with third-party endpoints.

Can I run FreeLLMAPI on a port other than 3001?

Yes. Specify your custom port when starting the server and pass the same URL to setup-claude. The --url parameter accepts any valid HTTP origin where your FreeLLMAPI instance is reachable.

Does this setup modify my existing Claude Code configuration?

The setup-claude command backs up existing configuration files before writing temporary settings. Run npx freellmapi launch to use the isolated configuration, or restore your backup manually if needed. The CLI avoids polluting your global Claude Code settings.

Which Claude models are available through FreeLLMAPI?

All Claude families (default, opus, sonnet, haiku) are supported. Map each to auto for router-driven selection or pin specific models in the dashboard. The proxy also implements token counting and model listing endpoints for full Anthropic API compatibility.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}