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 catalogs 22 provider groups spanning recurring free tiers, keyless endpoints, finite trials, pin-only routes, and disabled candidates (177 enabled chat routes), and automatically fails over only across enabled routes you can access. You can start without provider credentials when an enabled keyless route is available.

Release status: Latest release: 0.12.3. GitHub and PyPI both provide the Hermes profile, operational endpoints, refreshed providers, Vercel AI Gateway support, spread routing, and OpenCode registry-readiness hardening.

1. Install the release, then start the proxy

python -m pip install freellmpool
freellmpool proxy            # serves http://localhost:8080

The proxy now accepts both OpenAI (/v1/chat/completions) and Anthropic (/v1/messages) requests. It routes each request to an enabled target you can access and fails 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 (released in 0.12.0)

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. freellmpool's local per-day counters reset at UTC midnight; upstream providers use their own limit and reset windows.

3. Operational checks for agents and orchestrators

The 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 credentials for more capacity

If a keyless route is available it can get you started; adding applicable credentials for recurring free tiers such as Groq or Gemini can unlock more routes and capacity. Finite trials and priced or pin-only routes remain distinct. Each provider's current setup and caveats are listed in the accounts guide. freellmpool spreads load across enabled routes you can access and tracks local per-day usage.

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 included in release 0.12.0.

Part of freellmpool (MIT, free, open source). Updated 2026-08-29.