freellmpool › guide

How to run Claude Code, Codex, Hermes, or Aider on free LLM models

You can run Claude Code, OpenAI Codex, Hermes, Aider, Cline, Continue, or Cursor on free LLM tiers by pointing them at a local proxy that speaks the OpenAI API and has an experimental Anthropic-compatible path. The open-source tool freellmpool is that proxy: it pools the free tiers of 24 providers (Groq, Cerebras, NVIDIA, Gemini, OpenRouter, Cloudflare, Morph, Vercel, Mistral, Cohere and more) behind one endpoint, with automatic failover. Several providers need no API key, so you can start for free in under a minute and change no code in the agent.

Release status: GitHub and PyPI both provide 0.11.4. Released 0.11.4 includes spread routing. The Hermes profile and the operational endpoints below are newer, unreleased additions on current main. Replace the released package in your agent environment to use them:

python -m pip install --force-reinstall 'git+https://github.com/0xzr/freellmpool.git@main'

1. Choose a release or current-main install, then start the proxy

# Released 0.11.4:
python -m pip install freellmpool
# Or replace it with current main for Hermes and the operational endpoints:
python -m pip install --force-reinstall 'git+https://github.com/0xzr/freellmpool.git@main'

freellmpool proxy            # serves http://localhost:8080

That's all the setup. The proxy now accepts both OpenAI (/v1/chat/completions) and Anthropic (/v1/messages) requests and routes each to a free provider, failing over when one is rate-limited.

2. Point your agent at it

Claude Code

export ANTHROPIC_BASE_URL=http://localhost:8080
export ANTHROPIC_API_KEY=anything   # ignored
claude

Or run freellmpool code claude to print these steps. (The Claude Code path is experimental: text and tool use work; no vision yet.)

OpenAI Codex CLI

export OPENAI_BASE_URL=http://localhost:8080/v1
export OPENAI_API_KEY=anything
codex

Aider

export OPENAI_API_BASE=http://localhost:8080/v1
export OPENAI_API_KEY=anything
aider --model gpt-4o-mini      # alias resolves to a free model

Hermes Agent (current main; unreleased)

Hermes supports a custom OpenAI-compatible endpoint. The print-only profile shows the supported config without editing ~/.hermes/config.yaml:

freellmpool profile install hermes
freellmpool profile doctor hermes --dry-run
# Or run: hermes model → Custom endpoint → http://localhost:8080/v1

Cline, Continue, and Cursor work the same way — set the OpenAI base URL to the proxy. Run freellmpool code <agent> for the exact per-agent setup.

Free-tier models are smaller than frontier models. They're good for scaffolding, refactors, tests, commit messages, and everyday edits — not a substitute for a frontier model on the hardest reasoning. Limits reset at UTC midnight.

3. Operational checks for agents and orchestrators (current main)

The current-main proxy exposes public /livez liveness and advisory /readyz readiness. Authenticated automation can inspect the secret-free /v1/providers inventory or request only locally ready models with /v1/models?ready=true. Readiness is a local quota/cooldown snapshot; it does not probe upstream providers.

4. (Optional) add free keys for more capacity

The keyless providers get you started; adding free API keys for Groq, Cerebras, Gemini and others unlocks more models and higher daily limits. Each provider's free signup is listed in the accounts guide. freellmpool spreads load across whatever you have and tracks per-day usage so you drain each tier evenly.

FAQ

Can I really use Claude Code for free?

Yes, for the experimental text/tool-use path: freellmpool's proxy implements the Anthropic Messages API and routes it to free models, so Claude Code runs against them with no code changes. Quality is bounded by the free-tier models, and there's no vision support yet.

Is this against the agents' terms?

You're pointing the agent at a different OpenAI-compatible endpoint, or at freellmpool's experimental Anthropic-compatible path — the same mechanism those tools officially support for custom base URLs and local models. You're using the LLM providers' own free tiers; don't abuse them.

Which coding agents are supported?

Any tool that lets you set an OpenAI or Anthropic base URL: Claude Code, OpenAI Codex CLI, Hermes, Aider, Cline, Continue, Cursor, OpenCode, and more. Hermes' first-class profile is currently on main rather than in released 0.11.4.

Part of freellmpool (MIT, free, open source). Updated 2026-07-19.