---
title: "Free Claude Code Explained: One Local Proxy for 50+ AI Providers"
description: "Free Claude Code routes Claude Code, Codex, Pi, and eight more agents through one local proxy with 50 ToS-friendly providers and automatic fallback."
pubDate: "2026-08-27"
lang: "en"
slug: "free-claude-code-explained"
url: "https://hoangyell.com/free-claude-code-explained/"
author: "HoangYell"
translation_vi: "https://hoangyell.com/vi/free-claude-code-explained/"
categories: ["AI & Agents"]
tags: ["ai", "claude", "developer-tools", "claude-code", "ai-agents"]
heroImage: "https://raw.githubusercontent.com/HoangGeek/store/refs/heads/main/webp/free-claude-code-explained.webp"
---

You want Claude Code, Codex, or Pi - but you do not want a second subscription, a sketchy reverse proxy, or a setup that breaks the moment one provider rate-limits you.

Then **[free-claude-code](https://github.com/Alishahryar1/free-claude-code)** shows up with 50k+ GitHub stars and a promise: *1.3B+ free tokens, nine coding agents, ToS friendly*. Sounds too good. What is the catch?

The catch is simpler than you think: FCC is not a magic free API. It is a **local proxy + admin layer** that sits between your coding agents and the providers you already have access to - free tiers, subscriptions, API keys, or local models. One install, one config UI, many agents.

Repository: [Alishahryar1/free-claude-code](https://github.com/Alishahryar1/free-claude-code)

***

## TL;DR

![Image](https://raw.githubusercontent.com/HoangGeek/store/refs/heads/main/webp/free-claude-code-explained-gallery-01.webp)

- **What it does:** Runs `fcc-server` on your machine; agents talk to `localhost:8082` instead of Anthropic/OpenAI directly.
- **Pain without it:** Separate API keys per agent, manual model switching when a provider fails, and gray-area proxies that risk account bans.
- **What changes:** One Admin UI configures 50+ providers, ordered fallbacks, tier routing (Opus/Sonnet/Haiku), and launchers like `fcc-claude` / `fcc-codex`.
- **Who should use it:** Developers juggling free tiers or multiple providers who want Claude Code's UX without vendor lock-in.
- **Who should skip it:** Teams with a single paid Anthropic contract and no appetite for local Python infra.

Before FCC, every coding agent is its own island: its own env vars, its own API key drawer, its own outage story.

```markdy
scene width=1280 height=720 duration=8
theme: light=doodle dark=nebula
layout auto

user Dev "Developer"
service Claude "Claude Code"
service Codex "Codex"
service Pi "Pi Agent"
database KeysA "Anthropic Key"
database KeysB "OpenAI Key"
database KeysC "Groq Key"
policy Outage "Provider Outage"
service Admin "Manual Switch"

beat chaos "Every agent owns its provider" {
  show $nodes stagger=60ms
  Dev -> Claude "ANTHROPIC_API_KEY"
  Dev -> Codex "OPENAI_KEY"
  Dev -> Pi "GROQ_KEY"
  Claude -> KeysA "direct"
  Codex -> KeysB "direct"
  Pi -> KeysC "direct"
  KeysA -> Outage "rate limit"
  KeysB -> Outage "quota hit"
  Admin -> Claude "edit .env"
  Admin -> Codex "restart"
  glow Outage color=#ef4444
  glow Admin color=#ef4444
}

player:
    playback:
      loop true
    controls:
      speed true
      speeds "0.25"
      fullscreen true
      gif true
      theme true
    interaction:
      zoom true
      pan true
      click_to_play true
      double_click_to_reset true
      keyboard false
    chrome:
      badge true
      progress none
```

FCC collapses that into one control point: agents hit the local proxy; the proxy picks the model, retries, and falls through your ordered provider list.

```markdy
scene width=1280 height=720 duration=8
theme: light=doodle dark=nebula
layout auto

user Dev "Developer"
service Agents "Claude Codex Pi"
service FCC "fcc-server :8082"
service Admin "Admin UI"
database Catalog "50+ Providers"
database Fallback "Fallback Chain"
jwt Route "Model Route"
service RTK "RTK + Optimizations"

beat model "One proxy, many agents" {
  show $nodes stagger=60ms
  Dev -> Agents "fcc-claude fcc-codex"
  Agents -> FCC "localhost"
  Admin -> Catalog "NVIDIA NIM Groq OpenRouter"
  FCC -> Catalog "primary model"
  Catalog -> Fallback "on failure"
  Fallback -> Route "next provider"
  Agents <- Route "same turn"
  FCC -> RTK "fewer tokens"
  glow FCC color=#22c55e
  glow Catalog color=#22c55e
  glow Fallback color=#22c55e
}

player:
    playback:
      loop true
    controls:
      speed true
      speeds "0.25"
      fullscreen true
      gif true
      theme true
    interaction:
      zoom true
      pan true
      click_to_play true
      double_click_to_reset true
      keyboard false
    chrome:
      badge true
      progress none
```

Keep the pair in mind: **without FCC**, you are the integration layer. **With FCC**, the proxy is.

***

## Beginner Map

![Image](https://raw.githubusercontent.com/HoangGeek/store/refs/heads/main/webp/free-claude-code-explained-gallery-02.webp)

Read this post against the two scenes above:

1. **Pass 1:** See why per-agent API keys become operational debt.
2. **Pass 2:** Memorize `fcc-server` → Admin UI → `fcc-claude` (or `fcc-codex`).
3. **Pass 3:** Learn the vocabulary: `MODEL`, fallback list, tier overrides, RTK.
4. **Pass 4:** Run the first exercise below on your machine.

| Term | Question it answers |
|:---|:---|
| **`fcc-server`** | What process listens on `localhost:8082`? |
| **Admin UI** | Where do I paste API keys and pick models? |
| **`MODEL`** | Which provider/model handles a request by default? |
| **Fallback Models** | What runs when the primary provider fails? |
| **`fcc-claude`** | How does Claude Code reach FCC instead of Anthropic? |
| **RTK** | How does FCC shrink noisy terminal output before it hits the model? |

### First Practical Exercise

Install FCC, start the server, paste one free provider key (NVIDIA NIM is the README default), validate, apply, then run:

```bash
fcc-claude
```

Inside Claude Code, open `/model` and confirm FCC models appear. If they do, the "with" scene is real - everything else is configuration detail.

**Stretch goal:** Add a second provider to **Fallback Models**, then temporarily break the primary key. Watch the same agent turn continue on the backup without a manual restart.

***

## Part 1: Foundations - the mental model

![Image](https://raw.githubusercontent.com/HoangGeek/store/refs/heads/main/webp/free-claude-code-explained-gallery-03.webp)

Think of coding agents as **appliances** and model providers as **power companies**. Claude Code expects Anthropic-shaped electricity. Codex expects OpenAI-shaped electricity. Groq, Gemini, and local Ollama each speak slightly different dialects.

Without an adapter, you buy a separate wall plug for every appliance. With FCC, you install **one power strip with a smart router**: the appliance plugs into `localhost:8082`; FCC translates the request, bills the right provider, and switches circuits when one trips.

That is the central control point in the "with" scene: **`fcc-server` is not the model - it is the router**.

```markdy
scene width=1280 height=720 duration=8
theme: light=doodle dark=nebula
layout auto

client Agent "Coding Agent"
service Plug "localhost 8082"
service FCC "fcc-server"
cloud Cloud "NIM Groq OpenRouter"
database Local "Ollama LM Studio"

beat adapter "One socket, many circuits" {
  show $nodes stagger=60ms
  Agent -> Plug "Anthropic-shaped"
  Plug -> FCC "translate"
  FCC -> Cloud "cloud keys"
  FCC -> Local "local models"
  glow FCC color=#22c55e
  glow Plug color=#22c55e
}

player:
    playback:
      loop true
    controls:
      speed true
      speeds "0.25"
      fullscreen true
      gif true
      theme true
    interaction:
      zoom true
      pan true
      click_to_play true
      double_click_to_reset true
      keyboard false
    chrome:
      badge true
      progress none
```

Important nuance the star count hides: FCC does not generate tokens for free out of thin air. It aggregates **legitimate free tiers and keys you supply**. The "1.3B+ free tokens" headline is the sum of documented monthly allowances across cataloged providers - each with its own limits, terms, and availability. FCC's value is **orchestration**, not alchemy.

The project is also explicit: *independent open-source, not affiliated with Anthropic*. Claude and Claude Code are Anthropic trademarks. FCC routes **to** compatible endpoints; it does not replace Anthropic's product or support.

***

## Part 2: The Investigation - what actually happens?

![Image](https://raw.githubusercontent.com/HoangGeek/store/refs/heads/main/webp/free-claude-code-explained-gallery-04.webp)

Here is the happy path from zero to coding, mapped to the scene arrows.

### Step 1: Install or update

Review the installer before you pipe it. Then pick your OS.

macOS/Linux:

```bash
curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.sh" | sh
```

Windows PowerShell:

```powershell
& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.ps1")))
```

Re-run the same command to update. When prompted, choose at least one coding agent and optionally **RTK** - a filter that strips repetitive terminal noise so fewer tokens reach the model.

Nine launchers after install:

| Command | Agent |
|:---|:---|
| `fcc-claude` | Claude Code |
| `fcc-codex` | Codex |
| `fcc-pi` | Pi |
| `fcc-opencode` | OpenCode |
| `fcc-cline` | Cline |
| `fcc-hermes` | Hermes |
| `fcc-dsh` | DeepSeek Harness |
| `fcc-grok` | Grok Build |
| `fcc-muse` | Muse Code |

### Step 2: Start `fcc-server`

- **macOS/Windows:** Launch **Free Claude Code** from Applications or Start menu.
- **Linux:** Run `fcc-server` and keep the terminal open.

The server prints an Admin UI URL. Tray/menu-bar icons on desktop OSes expose restart and quit.

### Step 3: Configure a provider in Admin UI

Example with NVIDIA NIM (README default):

1. Create a key at [build.nvidia.com/settings/api-keys](https://build.nvidia.com/settings/api-keys).
2. Open Admin UI → paste `NVIDIA_NIM_API_KEY`.
3. Leave `MODEL` on `nvidia_nim/nvidia/nemotron-3-super-120b-a12b` or search the dropdown.
4. **Validate** → **Apply**.

Optional: enable **Proxy Authentication** so only clients with the bearer token can hit the proxy.

**ChatGPT is not an API key.** Open **Providers → Connected accounts**, sign in with the official ChatGPT flow (device code on headless boxes), then restart any already-running agent. OpenAI-shaped clients then use `openai/<model-id>`.

### Step 4: Launch an agent through FCC

```bash
fcc-claude    # Claude Code
fcc-codex     # Codex
fcc-pi        # Pi
fcc-opencode  # OpenCode
fcc-cline     # Cline
fcc-hermes    # Hermes
fcc-dsh       # DeepSeek Harness
fcc-grok      # Grok Build
fcc-muse      # Muse Code
```

Each launcher sets the env vars that agent expects (`ANTHROPIC_BASE_URL`, OpenAI-compatible base URL, etc.) to point at FCC instead of the vendor cloud.

### Step 5: IDE integration (optional)

For **Claude Code in VS Code**, point `ANTHROPIC_BASE_URL` at `http://localhost:8082` and set `ANTHROPIC_AUTH_TOKEN` to match Admin UI. Enable `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` so `/model` lists FCC catalog entries.

For **Codex App**, add an `fcc` model provider in `~/.codex/config.toml` with `base_url = "http://127.0.0.1:8082/v1"` and auth via `fcc-codex --print-proxy-auth-token`.

### What happens on each request?

1. Agent sends an Anthropic- or OpenAI-shaped request to FCC.
2. FCC resolves `MODEL` (or tier override - see Part 3).
3. FCC calls the provider adapter (NVIDIA NIM, OpenRouter, Groq, local Ollama, …).
4. On failure after retries, FCC walks **Fallback Models** in order - same turn, no agent restart.
5. Optional RTK and five built-in optimizations trim command output and metadata before the next provider call.

The README claims up to **90% fewer terminal-output tokens** when RTK is enabled - meaningful when agents dump build logs into context.

```markdy
scene width=1280 height=720 duration=10
theme: light=doodle dark=nebula
layout TB

client Agent "Coding Agent"
service FCC "fcc-server"
service Pick "Model Resolver"
service P1 "Primary Provider"
service P2 "Fallback Provider"
database RTK "RTK Filter"
user Dev "Developer"

beat flow "One request, automatic failover" {
  show $nodes stagger=55ms
  Agent -> FCC "chat completion"
  FCC -> RTK "strip noise"
  RTK -> Pick "resolve MODEL"
  Pick -> P1 "try primary"
  P1 -> FCC "429 or timeout"
  Pick -> P2 "next in list"
  P2 -> Agent "response"
  Dev -> FCC "Admin UI config"
  glow FCC color=#3b82f6
  glow P2 color=#22c55e
}

player:
    playback:
      loop true
    controls:
      speed true
      speeds "0.25"
      fullscreen true
      gif true
      theme true
    interaction:
      zoom true
      pan true
      click_to_play true
      double_click_to_reset true
      keyboard false
    chrome:
      badge true
      progress none
```

***

## Part 3: The Diagnosis - terms that cause confusion

![Image](https://raw.githubusercontent.com/HoangGeek/store/refs/heads/main/webp/free-claude-code-explained-gallery-05.webp)

### `provider-id/model-id` slugs

Models in Admin UI use a two-part slug: `open_router/openrouter/free`, `groq/llama-3.3-70b-versatile`, `ollama/llama3.1`. The prefix selects the adapter; the suffix is the provider's exact model identifier. If a provider cannot list models, type the slug manually.

### Tier routing (Fable, Opus, Sonnet, Haiku)

Claude Code internally labels tiers. FCC lets you map each tier to a different backend:

- `MODEL` - default for everything.
- `MODEL_OPUS`, `MODEL_SONNET`, `MODEL_HAIKU`, `MODEL_FABLE` - overrides per tier; **None** inherits `MODEL`.

Example strategy: Opus-tier tasks on a large free NIM model, Haiku-tier on a fast local `lmstudio/` tag, default `MODEL` on OpenRouter free.

```markdy
scene width=1280 height=720 duration=8
theme: light=doodle dark=nebula
layout TB

client CC "Claude Code"
service FCC "fcc-server"
service Opus "MODEL_OPUS"
service Sonnet "MODEL_SONNET"
service Haiku "MODEL_HAIKU"
service Def "MODEL default"

beat tiers "Route by Claude Code tier" {
  show $nodes stagger=60ms
  CC -> FCC "request + tier"
  FCC -> Opus "heavy"
  FCC -> Sonnet "balanced"
  FCC -> Haiku "cheap fast"
  FCC -> Def "unset tier"
  glow FCC color=#3b82f6
}

player:
    playback:
      loop true
    controls:
      speed true
      speeds "0.25"
      fullscreen true
      gif true
      theme true
    interaction:
      zoom true
      pan true
      click_to_play true
      double_click_to_reset true
      keyboard false
    chrome:
      badge true
      progress none
```

### Reasoning control

**Admin UI → Model Config → Reasoning** can force effort off/low/high or pass through what the client sends. Providers that ignore reasoning flags keep their native behavior - FCC does not fabricate chain-of-thought.

### Messaging integrations (Discord / Telegram)

FCC is not only terminal-first. Configure **Admin UI → Messaging** to run agents from chat, with `/stats`, `/stop`, and `/clear` commands. Voice notes optional via local Whisper or NVIDIA NIM transcription - closer to OpenClaw's omnichannel pitch, but scoped to **coding-agent sessions** in an allowed directory.

### "ToS friendly" - what that actually means

FCC markets compliance: use official APIs and subscription flows (e.g. ChatGPT connect in Admin UI), remove integrations when providers disallow them. That is **not** a guarantee your account is safe - provider terms change. Treat free tiers as **best-effort**, read each provider's limits, and avoid sharing one key across abusive automation.

### FCC vs. unofficial Claude proxies

| Approach | Risk profile | What you get |
|:---|:---|:---|
| Random "free Claude API" relay | High - often violates ToS, keys leaked | Fragile, account ban roulette |
| Direct Anthropic API | Low - official | Full fidelity, pay per token |
| **FCC** | Medium - depends on providers **you** configure | Multi-agent, multi-provider, local control |

***

## Part 4: The Resolution - tradeoffs and when to use it

![Image](https://raw.githubusercontent.com/HoangGeek/store/refs/heads/main/webp/free-claude-code-explained-gallery-06.webp)

### When FCC shines

- You already bounce between **free tiers** (NIM, OpenRouter free, Groq, Gemini flash) and want one config surface.
- You run **multiple agents** (Claude Code + Codex + Pi) and refuse to duplicate keys in three env files.
- Provider outages are common in your region - **ordered fallback** saves a half-finished refactor.
- You want **local or hybrid models** (Ollama, LM Studio, llama.cpp) in the same picker as cloud models.
- You experiment from **phone or chat** via Discord/Telegram without building OpenClaw-scale automation.

### When to skip or defer

- Your team standardizes on **one Anthropic enterprise contract** - adding a Python proxy is pure ops overhead.
- You need **vendor SLAs, audit trails, and support tickets** - FCC is MIT hobby infra, not a managed gateway.
- You cannot run a **persistent local service** (locked-down corp laptop, ephemeral CI only).
- You expect **frontier-model fidelity** every session - free routes may lag newest Opus capabilities.

### Compared to OpenClaw

[OpenClaw](/openclaw-explained/) is a **proactive personal operator** across messaging, cron, and OS nodes. FCC is a **model router for coding agents**. They solve different layers: OpenClaw decides *when* to act; FCC decides *which model answers* when Claude Code already has a prompt. You could run both - OpenClaw triggering tasks, FCC backing the coding session - but neither replaces the other.

```markdy
scene width=1280 height=720 duration=8
theme: light=doodle dark=nebula
layout TB

decision Need "Need AI coding"
service Direct "Direct API"
service FCC "FCC proxy"
service OpenClaw "OpenClaw"
service Simple "One vendor"
service Multi "Many providers"
service Ops "Local service"
service Auto "Proactive agent"

beat compare "Pick the right layer" {
  show $nodes stagger=60ms
  Need -> Direct "paid contract"
  Direct -> Simple "lowest ops"
  Need -> FCC "free tiers + agents"
  FCC -> Multi "catalog + fallback"
  FCC -> Ops "fcc-server"
  Need -> OpenClaw "24/7 operator"
  OpenClaw -> Auto "cron + chat"
  glow FCC color=#22c55e
  glow Direct color=#3b82f6
  glow OpenClaw color=#a855f7
}

player:
    playback:
      loop true
    controls:
      speed true
      speeds "0.25"
      fullscreen true
      gif true
      theme true
    interaction:
      zoom true
      pan true
      click_to_play true
      double_click_to_reset true
      keyboard false
    chrome:
      badge true
      progress none
```

### Minimal production-minded setup

1. Run `fcc-server` on a machine that stays awake (home server or dev box).
2. Enable **Proxy Authentication** if the port is reachable on your LAN.
3. Configure **two providers minimum** - primary + fallback.
4. Pin versions: re-run the install script to update; check `fcc-server --version` before upgrades.
5. Keep Claude Code onboarding happy: set `"hasCompletedOnboarding": true` in `~/.claude.json` if login prompts persist after FCC config.

***

## Final Take

![Image](https://raw.githubusercontent.com/HoangGeek/store/main/webp/ai-free-claude-code-explained-04.webp)

**Free Claude Code is a universal adapter for coding agents** - not a free lunch, but a local control plane that makes free tiers, subscriptions, and local models look like one catalog to Claude Code, Codex, and friends.

One sentence to remember: *point every agent at `localhost:8082`, let FCC own the provider chaos.*

**Do this today:** install FCC, configure one free provider, run `fcc-claude`, and add a fallback model before your next long refactoring session.