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 (178 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.13.0. 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. For streaming requests, failover is possible only before the downstream event stream is committed. A later upstream error is reported in that protocol and never followed by a successful terminal event.

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.) Text-only Anthropic Messages requests stream incrementally; tool use and richer content remain buffered until translation is complete.

OpenAI Codex CLI

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

The Responses bridge emits text-only events incrementally and in protocol order. Tool calls and richer Responses inputs remain on the buffered compatibility path.

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.

Open http://localhost:8080/dashboard or /playground for the unified browser shell. The public HTML contains no usage or provider data. When proxy auth is configured, enter its token in the page: the input is cleared immediately, the bearer is sent only in Authorization headers, and it stays only in the page's JavaScript closure until reload. It is not stored in the URL, cookies, Web Storage, rendered page, globals, or logs.

freellmpool capacity status          # cache-first; no external refresh
freellmpool capacity status --refresh
freellmpool doctor                   # strict, secret-safe config diagnostics

4. (Optional) add a local model runtime

freellmpool local discover
freellmpool local discover --name ollama
freellmpool local import --name ollama --yes
# Use the exact provider/model pin printed by import.
freellmpool local remove local_ollama --yes

Discovery is explicit and bounded. It checks only fixed LM Studio, Ollama, and llama.cpp endpoints, or one canonical literal-loopback URL you supply. It sends no credentials, follows no redirects, and performs no DNS, LAN, or process scan. Import requires confirmation, adds pin-only routes without changing automatic routing, and can remove only its own managed catalog block.

5. (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.