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

> Easily configure Claude Code with FreeLLMAPI. Follow this guide to point to your local proxy and set the ANTHROPIC_AUTH_TOKEN for seamless integration.

- Repository: [Tashfeen/freellmapi](https://github.com/tashfeenahmed/freellmapi)
- Tags: how-to-guide
- Published: 2026-08-28

---

**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:

```bash
npm i -g freellmapi

```

Start the proxy server on the default port:

```bash
freellmapi start

```

The server exposes a base URL at `http://localhost:3001/v1` according to [`docs/api.md`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/cli/src/tools.ts) and documented in [`README.md`](https://github.com/tashfeenahmed/freellmapi/blob/main/README.md) lines 137-152.

Run the one-line setup:

```bash
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`](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/api.md) lines 341-357.

## Launching Claude Code

After configuration, start Claude Code using the provided launcher:

```bash
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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/api.md) lines 339-341.

Verify connectivity with a quick curl test:

```bash
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:

```bash

# 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.