ShelraCode on free models. What OpenRouter's free tier allows, and what the agent does with it.

Set it up

$ shelra auth openrouter <your-key>$ shelra

The key is stored in ~/.shelra/auth.json, never in your project; the OPENROUTER_API_KEY environment variable works too.

The limits OpenRouter sets

• 20 requests a minute on free models.
• 50 requests a day, or 1,000 a day once you have bought at least $10 of OpenRouter credits.
• The limits apply to your account: more keys or more accounts do not raise them. Past a limit, OpenRouter answers HTTP 429.

Source: OpenRouter's rate-limit documentation, checked on 2026-09-23. OpenRouter can change these limits; its page is the authority.

A coding task is many model requests, not one: each step of the agent is a request, and a step can make several tool calls. Field case 001, a real problem solved on nvidia/nemotron-3-ultra-550b-a55b:free, made 47 tool calls.

How the free policy picks a model

• It reads OpenRouter's live model catalog (cached for six hours) and keeps only the free models that support tool calling, the one capability an agent cannot work without.
• It ranks the free ones by a documented heuristic over what the catalog exposes (reasoning support, model size, context). That is not a benchmark, and ShelraCode does not present it as one.
• It routes to the best candidate, then the second, then openrouter/free, OpenRouter's own router, which picks a free model at request time: a busy model gives way to another free one instead of failing.
• A model you pin with shelra models use <id> or --model wins. A saved paid model is ignored under the free policy.
• A price the catalog does not report is treated as unknown, never as free.

When the free tier says no

A rate limit, an overloaded model or a stalled stream does not end the turn. The finished steps are kept, the round is retried after a pause, and after two failures in a row it moves to the next fallback. If no model answers for many attempts, the turn pauses with its progress saved and says how to resume. Only Esc ends a turn.

For work a daily limit would cut short, run the same agent on your own hardware: local mode has no request limit.

When you choose to pay

Paid routing is opt-in, with --model-policy auto, economy, balanced, quality or max. Spending caps run before each request is sent:

$ shelra --model-policy economy --max-cost 5 --max-request-cost 0.25

--max-cost caps the whole session in dollars and --max-request-cost a single request; a cap of 0 allows only requests the catalog prices at zero. When a price is unknown and a cap is set, the request is blocked until you refresh the catalog (shelra models --refresh).

What free models have shown so far

Field case 001, a real problem brought to ShelraCode, was solved on nvidia/nemotron-3-ultra-550b-a55b:free in 1 try; Claude Sonnet 5 needed 3. One case is one sample.

Every run of ShelraCode on a free model in the eight-task core suite, whatever its outcome:

The home page's benchmark table shows paid models: no core-suite run on a free model has completed on a public commit yet, and new runs appear here as they are recorded. Runs from before 2026-09-22 record commits from before the repository's history was rewritten, so they cannot be replayed from public commits. Every run is in the history.