DiFlowrin

Posted on Sep 3 Originally published at diflowrin.com

Free Claude Code and the Identity Question

#ai #github #git #programming

What Free Claude Code Actually Proves About Coding Agents

The story going around is that Free Claude Code works because an extension accepts a fake identity. It does not. It works because Claude Code was built to read two environment variables, ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN, and to send its requests wherever they point. That is a documented feature for corporate gateways, and Free Claude Code, an MIT-licensed Python project that runs a local AI proxy on your own machine, uses exactly that door. The real question is not whether the endpoint can be swapped. It is who is standing at the other end of it, and what your agent hands over when it gets there.

Why the Free Claude Code Debate Started at All

Coding agents got popular fast. Everyone has one open in a terminal or an editor, everyone burns through tokens, and everyone eventually looks at the bill. Then a project appears that says: run Claude Code, Codex, Pi, OpenCode and more, for free, from your terminal, app, IDE or phone. Of course people notice.

📹 Video: The BEST Free Claude Code Setup (Ollama + Proxy Tutorial)

Video credit: SelfTaughtDev

And then the second reaction comes. If it works without the vendor's own API, something must be broken. Right?

Wrong. We have to understand the plumbing. A coding agent is a client. It speaks a wire format, it sends an Authorization header, it reads a base URL from configuration. The vendor's own documentation describes an LLM gateway as a proxy your organisation runs between the agent and the model provider, and it tells you which variables to set for it. Enterprises asked for that. It shipped. Free Claude Code is a single developer using the same switch that a bank's platform team uses, on localhost instead of behind a corporate firewall.

So the interesting part is not the trick. There is no trick. The interesting part is what a configurable endpoint means for the person who configures it, and for the company whose laptops they configure it on.

Free Claude Code as a Local AI Proxy: How It Works

The repository is Alishahryar1/free-claude-code. Python, MIT licence, and its README says the thing plainly at the top: independent open-source project, not affiliated with or endorsed by Anthropic, Claude and Claude Code are trademarks of Anthropic. Credit where it is due, that disclaimer is doing more honest work than most of the commentary about it.

The mechanism, as the project describes it: you install with a shell or PowerShell one-liner, you start fcc-server (or the desktop launcher on Windows and macOS), and an Admin UI opens. You paste a provider key there, pick a model from a searchable dropdown, click Apply. Then you run your agent through a wrapper command: fcc-claude, fcc-codex, fcc-pi, fcc-opencode, fcc-cline, fcc-hermes, fcc-dsh, fcc-grok, fcc-muse, fcc-aider. Ten agents, one model catalog.

The Four Settings That Redirect the Agent

For the VS Code integration, the README asks you to add environment variables to your user settings JSON. This is the whole "identity" question, in four lines:

Setting	Value from the project's setup	What it does
`ANTHROPIC_BASE_URL`	http://localhost:8082	Sends agent requests to the local proxy instead of the vendor endpoint
`ANTHROPIC_AUTH_TOKEN`	`freecc`	Value used for the Authorization header; matched to the Admin UI
`claudeCode.disableLoginPrompt`	`true`	Stops the extension asking you to sign in
`CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY`	`1`	Lets the client discover models offered by the gateway

Notice what the token is. The word freecc. Not a signed credential, not a key with a checked prefix. And that is not a bug someone found: the vendor's environment-variable reference describes ANTHROPIC_AUTH_TOKEN as a custom value for the Authorization header, prefixed with Bearer, precisely because corporate gateways use their own token formats. Any string. By design.

Where the Trust Actually Sits in a Multi-Provider Model Router

So if there is no exploit, is there no risk? There is plenty. It just lives somewhere else than the headlines put it.

Think about what a coding agent sends. Your file contents. Your error strings. Your prompts, which are often a description of exactly where your system is weak. Point the base URL at a proxy and the proxy sees all of it, in cleartext if the URL is http://, which on localhost is fine, and on someone else's host is not fine at all. That is the actual lesson of a project like this, and it applies to every OpenAI-compatible gateway, not to one repository. Cline's own provider documentation walks users through setting a base URL and a key for any compatible endpoint, and the guidance is the same: it will not be the official vendor URL, so you had better know whose it is (Cline docs).

Bearer Token Authentication and Proxy Authentication in Practice

To its credit, the project takes the local surface seriously. The README says you can protect the local proxy with a bearer token by enabling Proxy Authentication in the Admin UI, and the Codex integration does not even ask you to paste a secret: it runs fcc-codex --print-proxy-auth-token as an auth command so the client reads the current token itself. That is a better pattern than a hardcoded string in a settings file, and it is worth copying.

The gap is not in the token. The gap is that a base URL is a trust decision, and nothing in a text field tells you how much trust you just spent.

Which AI Providers the Project Routes To, and Why That Matters

50 ToS-friendly providers. 1.3B+ free tokens every month. The project also states that it follows provider terms and removes integrations if they stop being allowed.Free Claude Code, project README

The provider catalog in the README is long and specific: NVIDIA NIM, OpenRouter, Groq, ClinePass, xAI, QwenCloud in two separate plan flavours, Together AI, DeepInfra, SiliconFlow, Nebius, Chutes, Featherless, ZenMux, W&B Inference, Azure OpenAI, Google AI Studio, Vertex AI, DeepSeek, Mistral and Codestral, OpenCode Zen and Go, Vercel AI Gateway, Amazon Bedrock, Hugging Face, Cohere, GitHub Models, Kimi, MiniMax, Cerebras, SambaNova, Kilo.ai, Fireworks, Novita, Cloudflare Workers AI, Z.ai, TokenRouter, NaraRoute, Poolside, LLM7.io, Ollama Cloud, plus local LM Studio, llama.cpp and Ollama. Each one has its own Admin UI setting and its own model slug format, like nvidia_nim/nvidia/nemotron-3-super-120b-a12b or groq/llama-3.3-70b-versatile.

The repository's own structure matches that claim rather than dressing it up. Under src/free_claude_code/providers/ the tree carries seventeen directories, including cloudflare, deepseek, gemini, github_models, groq, kilo, lmstudio, mistral, nvidia_nim, open_router, vertex. There is also a tests/providers/ directory, a tests/contracts/ directory, an ARCHITECTURE.md, a CONTRIBUTING.md and a uv.lock. This is a maintained codebase, not a gist.

And the honest caveat is the project's own: free-tier availability and limits are controlled by each provider and may change. Also, a fallback list can cost you twice. The README warns that a failed request may reach and consume usage from more than one provider before it succeeds.

Model Fallback Routing, Reasoning Control and the Rest of the Machinery

The features worth knowing about, as the project describes them:

Fallback models. An ordered list under Model Config. After retries are exhausted, the proxy tries your next configured model without making you restart the turn, across every connected client.
Tier routing. MODEL is the fallback for every request, while MODEL_FABLE, MODEL_OPUS, MODEL_SONNET and MODEL_HAIKU each override one Claude Code tier. Route the heavy tier to a hosted model, the cheap tier to a local one.
Reasoning control. Admin UI, Model Config, Reasoning: take the effort the client sent, turn it off, or override with Low through Max. Providers that do not support a control keep their own behaviour.
Token savings on terminal output. The project claims up to 90% fewer terminal-output tokens with the optional RTK filter, plus five in-proxy optimisations that answer quota probes, command-prefix detection, titles, suggestions and filepaths without calling a provider at all.
Surfaces. Native launchers, VS Code, the Codex App, JetBrains ACP, Discord, Telegram, and a local Chat Sessions view in Admin with persisted history, streaming, fallback and compaction.
Voice notes. Re-run the installer with --voice-nim, --voice-local or --voice-all for NVIDIA NIM or local Whisper transcription.

Compare that with a managed product, where the router is the vendor's business logic and you mostly get a picker. Cursor, for instance, documents a router that spans a fixed set of models and hides which one answered unless a team admin turns visibility on (Cursor Docs). Here the routing table is yours, and so is the responsibility for it.

Terms of Service, Not Certificates: Where the Argument Should Go

People reach for the word vulnerability because it sounds decisive. It is the wrong word here, and using it wrongly costs you the argument in the room where it matters.

Configurable endpoint

A documented client setting that sends agent traffic to a chosen host. Intended for gateways. Not an exploit.

Local proxy

A service on your own machine that receives agent requests and forwards them to a provider, translating formats along the way.

Provider terms

The contract that actually governs whether a given key may be used from a coding agent. The project flags specific plans as personal, interactive use only, and links each provider's own rules.

Read that last one again, because it is where a company gets hurt. The README notes that Kimi Code subscription keys and QwenCloud Coding Plan keys are for local, personal, interactive coding-agent use, with the keys and endpoints not interchangeable. A developer wiring a personal-use key into a team workflow is not a TLS problem. It is a compliance problem, and no certificate check would have caught it.

The client side is not defenceless either. The vendor's documentation states that when the base URL points at a non-first-party host, MCP tool search is disabled by default, and that as of v2.1.196 Remote Control is disabled when the base URL points anywhere other than api.anthropic.com. Features degrade on purpose once you leave the vendor's endpoint. That is a client that knows where it is.

What a Security Team Should Actually Do About It

Not panic. Not ban a repository. Treat the endpoint as the control point, because it is.

Manage the variables. If the base URL and the auth token can be set from a project file or an editor setting, then they are configuration you should be shipping and auditing, not discovering.
Log the hosts. You do not need to read prompts to know that agent traffic left for an address nobody approved.
Write the key policy down. Which provider plans may be used from a corporate machine, and which are personal-only. Then enforce it on keys, not on tools.
Prefer token helpers to pasted strings. The Codex setup in this project reads the proxy token through a command instead of hardcoding it. Do the same internally.
Separate the machines. A router that can reach forty-odd providers has no business sitting on a laptop with production credentials.

The ecosystem gap is real, but it is a standards gap, not a hole: agents authenticate to gateways with bearer strings and trust whatever answers in the right wire format, because that is what makes a gateway possible at all. Response signing, endpoint pinning by policy, and an agent that tells you loudly which host it is talking to would all help. None of them exist as a shared standard today. Until they do, the base URL field is the policy.

The Part Everyone Skips

Free Claude Code is a well-built local router with a long provider list, a real Admin UI, an MIT licence and a proxy token you can turn on. It is also a demonstration that the thing standing between your codebase and a stranger's server is a text field in a settings file. Both of those are true at the same time, and only one of them is the project's fault.

So use it as an argument, by all means. Just make the right one. Not "the extension accepts a fake identity", which will get you corrected by anyone who has read the gateway documentation. Say instead: our agents authenticate to whatever answers in the right format, we do not currently control or log where they point, and the credentials people wire in may not be licensed for the work they are doing. That version survives a meeting.

📊 What Engineering Leaders Should Take From This

No exploit, a documented door: Free Claude Code works through the same base-URL and auth-token variables enterprise gateways use.
The token was never the identity: the setup uses the literal string freecc, and the vendor's own reference describes that variable as accepting any string for the Authorization header.
Breadth is real and self-consistent: the project claims 50 providers and 1.3B+ free tokens monthly, and its providers/ folder holds 17 provider directories with tests and contract tests alongside.
Fallback has a cost: the project warns that one failed request may consume usage from more than one provider before it succeeds.
Your real exposure is licensing and egress: personal-use provider plans on corporate machines, and unlogged agent traffic to unapproved hosts. Control the endpoint and the keys, not the repository.

Additional Resources

This article includes content created with AI.

DEV Community