airroute
v1.0.6
Published
AirRoute — free AI gateway. One endpoint, many free providers, auto-fallback, adaptive auto routing, token compression, and a full admin console. Works with Claude Code, OpenCode, Cline, Copilot & any OpenAI/Anthropic-compatible agent.
Maintainers
Readme
AirRoute — free AI gateway
One endpoint, many free providers, auto-fallback. Install once, type airroute,
and it starts and opens the dashboard in your browser. Get a free Pollinations.ai
API key at enter.pollinations.ai/keys and set
POLLINATIONS_API_KEY in .env for zero-cost text generation.
Install & run
# from this project folder (installs the airroute command globally)
npm install -g .
npm link # (dev) live-links so rebuilds update the command instantly
# run it — starts the gateway AND opens http://localhost:8787/dashboard in your browser
airroute
# options
airroute --port 3000 # different port
airroute --config my.json # alternative config
airroute --no-browser # start without opening the dashboardAdd free-tier keys in .env or in the console (Providers tab). It works with
just one key (others are skipped by failover). Pollinations.ai requires a free
API key from enter.pollinations.ai/keys;
set POLLINATIONS_API_KEY in .env. Rebuild after changing code:
npm run build (the npm link install picks it up automatically).
Your base URL is http://localhost:8787. There are two APIs: OpenAI-compatible
http://localhost:8787/v1 and Anthropic-compatible http://localhost:8787.
Models: default, coder, fast, auto, or any provider/model.
Connecting your tools
Claude Code (Anthropic API)
export ANTHROPIC_BASE_URL=http://localhost:8787
export ANTHROPIC_AUTH_TOKEN=airroute # any non-empty value
# model: gpt-oss-20b / coder / auto / etc.Set ANTHROPIC_MODEL=coder to pick a route.
OpenCode (OpenAI API)
export OPENAI_BASE_URL=http://localhost:8787/v1
export OPENAI_API_KEY=airroute # any value; keys are checked by the gateway
# opencode run --model default "write tests"Cline (VS Code extension)
Settings → API Provider → OpenAI Compatible:
- Base URL:
http://localhost:8787/v1 - API Key: any value (e.g.
airroute) - Model ID:
default,coder,fast, orauto
Continue (VS Code, config.json)
"models": [{
"title": "AirRoute",
"provider": "openai",
"model": "coder",
"apiBase": "http://localhost:8787/v1",
"apiKey": "airroute"
}]Cursor
Settings → Models → OpenAI API Key and Base URL (http://localhost:8787/v1) — Cursor allows a custom OpenAI base URL / override.
Generic OpenAI tools (Continue, Copilot-style, SDKs)
export OPENAI_BASE_URL=http://localhost:8787/v1
export OPENAI_API_KEY=airrouteThe bundled local agent
node dist/index.js --via gateway "add unit tests for the auth module"
node dist/index.js --via gateway --model coder "refactor the API layer"Quick health check
curl http://localhost:8787/health
curl -X POST http://localhost:8787/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"auto","messages":[{"role":"user","content":"Say hi"}]}'The console (Providers tab) shows live health and lets you add/edit providers with no restart.
Publishing to npm (optional)
The package ships compiled dist only — no source, no .env, no gateway.config.json.
All keys are read from environment variables at runtime, so no secrets ever leave
your machine.
# verify nothing sensitive is in the tarball (should list only dist/ + package.json + README + LICENSE)
npm pack --dry-run
# publish (one-time), then install anywhere with:
npm login
npm publish
# npm i -g airroutenpm now requires a paid npm account (payment verification) to publish unscoped packages. If you don't want that, you can still install from this folder with
npm install -g ./npm linkand get the exact sameairroutecommand.
Set keys on the machine that runs AirRoute, e.g.:
export OPENROUTER_API_KEY=... GEMINI_API_KEY=... GROQ_API_KEY=...
airrouteOr drop a .env in the directory you run airroute from.
Local AI Coding Agent
A separate, optional tool in the same repo: a lightweight locally run coding agent.
It can use Ollama (100% local, no costs) or drive the AirRoute free-provider
gateway (--via gateway).
Features
- Tool-using agent loop — runs shell commands, reads/writes/edits files, lists directories, greps, and globs to autonomously complete tasks.
- 100% local — everything runs against
http://localhost:11434. No API keys, no usage bills. - Model-agnostic — works with any Ollama tool-calling model. Pick quality or speed freely.
- Self-pulling — auto-downloads the chosen model on first run.
Install
# 1. Install Ollama (the local model server)
# https://ollama.com/download -> then start it: ollama serve
# 2. Install Node.js 18+ (already have it? skip)
# 3. In this folder:
npm install
npm run build
# 4. Now use it:
node dist/index.js "explain this project and add unit tests"Usage
node dist/index.js "task or question"
node dist/index.js --model qwen3:8b "refactor the auth module"
node dist/index.js --model qwen2.5-coder:7b "add a ./scripts build step" --maxSteps 40| Option | Default | Description |
| ----------------- | ------------------------- | ------------------------------ |
| --model <name> | qwen3:8b | Ollama model to use |
| --host <url> | http://localhost:11434 | Ollama endpoint |
| --temperature | 0.2 | Sampling temperature |
| --context | 8192 | Context window (tokens) |
| --maxSteps | 25 | Max agent iterations |
Environment variables: AGENT_MODEL, OLLAMA_HOST, AGENT_TEMP, AGENT_CTX, AGENT_MAX_STEPS.
Recommended free models
| Model | Notes |
| -------------------- | ---------------------------------------- |
| qwen3:8b | Great tool-calling + reasoning balance |
| qwen2.5-coder:7b | Strong code generation |
| llama3.2:3b | Fast, low RAM |
| llama3.1:8b | General purpose |
Pull one explicitly, or let the agent pull the default for you:
ollama pull qwen3:8bHow it works
CLI (src/index.ts)
-> config (src/config.ts) model + agent settings
-> agent loop (src/agent.ts) asks the model, executes tools, iterates
-> tools (src/tools.ts) bash/read/write/edit/list/grep/glob
-> Ollama client (src/ollama.ts) POST /api/chat with tool-callingThe agent inspects your repo, makes changes, then builds/tests to verify — fixing failures until the task is done.
Development
npm run dev # run src via tsx
npm run build # build dist/
npm run typecheck # type-check onlyNotes & limits
- Quality depends on your hardware and the model you pick. Bigger context windows
cost more RAM (
OLLAMA_HOSTserves localhost only). - The
greptool usesripgrep(rg); ensure it's on your PATH for searches. - On Windows, shell commands use PowerShell; on macOS/Linux they use
sh.
Local Gateway (free-provider router, like Omniroute)
A separate tool in the same repo: a local HTTP router/proxy that aggregates multiple free-tier providers behind one endpoint. It exposes both OpenAI-compatible and Anthropic-compatible APIs, with automatic failover, so you can point real agent CLIs (OpenCode, Kilo, Cline, Continue, Claude Code, …) at it and never pay for API calls.
Quick start
# 1. Copy the env template and fill in free API keys (all optional)
cp .env.example .env
# - OPENROUTER_API_KEY (openrouter.ai/keys — free :free models)
# - GEMINI_API_KEY (aistudio.google.com/apikey — free tier)
# - GROQ_API_KEY (console.groq.com/keys)
# - GITHUB_TOKEN (github.com/settings/tokens — GitHub Models)
# - CF_ACCOUNT_ID + CF_API_TOKEN (Cloudflare Workers AI)
# 2. Build + run
npm run build
npm run gatewayStartup prints the URL and warns about any provider missing a key (those are skipped during failover, so it still works with just one key).
Pointing agents at it
OpenAI-compatible (OpenCode, Kilo, Cline, Continue…)
# base URL http://localhost:8787/v1
# model one of: default, coder, fast, or provider/model
OPENAI_BASE_URL=http://localhost:8787/v1Claude Code (Anthropic-compatible)
ANTHROPIC_BASE_URL=http://localhost:8787
ANTHROPIC_AUTH_TOKEN=anything
# model: default / coder / fastRouting & failover
- A route (e.g.
default,coder,fast) is an ordered list ofprovider/model. Requests try each in order; on rate-limit or error the gateway falls through to the next. Free tiers get rate-limited often, so this keeps you running. - You can also call any model directly as
provider/model, e.g.gemini/gemini-2.5-flash. - Add your own routes/providers in
gateway.config.json(seegateway.config.example.json).
Endpoints
| Endpoint | API | Purpose |
| --- | --- | --- |
| POST /v1/chat/completions | OpenAI | chat + streaming, tool calls |
| POST /v1/messages | Anthropic | chat + streaming, tool use (Claude Code) |
| GET /v1/models | OpenAI / Anthropic | list route + provider models |
| POST /v1/messages/count_tokens | Anthropic | token estimate |
| GET /health | — | status |
Providers: OpenRouter, Gemini, Groq, GitHub Models, Cloudflare
Workers AI. Add any OpenAI-compatible provider by editing gateway.config.json.
Usage dashboard & stats
GET /stats— JSON snapshot: per-route and per-provider calls, OK/failures, 429s, token counts, in-flight requests, and cooldown state.GET /dashboard— full admin console with a sidebar and live UI:- Dashboard — usage cards, per-provider/per-route tables, live health badges
- Providers — list, add, edit, and delete providers from the UI (no JSON editing). Health probe + key status per provider.
- Routes — add / edit / delete failover chains (one
provider/modelper step). - Models — every requestable model id across providers and routes.
- Changes made in the console save to
gateway.config.jsonand apply immediately (no restart). The config file is gitignored.
Management API (used by the console): GET /api/config, GET /api/health,
POST|DELETE /api/providers, POST|DELETE /api/routes.
Smart rate-limit handling
The gateway tracks each provider's responses. After a 429 it cools the provider
down for 30s (5xx → 8s) and skips it during failover instead of hammering it.
Cooldown state is visible in /stats as cooldownRemainingMs.
OmniRoute-style smarts
automodel — an adaptive route. Instead of a fixed chain it picks among all usable providers, skips cooled-down ones, and prefers the lowest recent latency while rotating so no single provider gets hammered.model: "auto"works on both the OpenAI and Anthropic endpoints.- Token compression (on by default) — long conversations are compacted before
they reach a provider: oldest plain-text turns are pruned and oversized messages
truncated when the request exceeds
GATEWAY_COMPRESS_BUDGET(default 64000). SetGATEWAY_COMPRESS=0to disable. Context errors are also caught and retried automatically with compression. - Free Tiers page — console → Free tiers shows each provider's approximate
monthly free allowance, what you've used, remaining budget, and which ones are
free forever.
GET /api/freetiers. - Pollinations.ai free credits — sign up at enter.pollinations.ai/keys
for free Pollen credits. Models:
openai,kimi,deepseek,glm,claude-fast.
Providers
13 pre-wired providers. Pollinations.ai requires a free API key from enter.pollinations.ai/keys. Free tiers that just need a key: OpenRouter, Gemini, Groq, Mistral, Cerebras, DeepSeek, Together, Z.AI GLM-Flash (Cloudflare needs an account ID). Add any OpenAI-compatible provider from the console (Providers → + Add Provider).
Free models without restrictions
- Pollinations.ai — free Pollen credits on signup, no credit card required.
Models:
openai,kimi,deepseek,glm,claude-fast,gemini-large,qwen3.8-max. Get your key at enter.pollinations.ai/keys. - OpenRouter free models — gpt-oss-20b, Gemma-4-31B, Cohere North, Nemotron-3, Llama-4-Maverick, Mistral-Small-3.1-24B (rate-limited but free).
- Z.AI GLM-Flash — free forever, no token cap.
- Groq — 8M tokens/month free, very fast inference.
- Gemini — 60M tokens/month free via Google AI Studio.
Use the local agent with the gateway
The same agent can drive the free-provider gateway instead of Ollama:
node dist/index.js --via gateway "add unit tests for the auth module"
node dist/index.js --via gateway --model coder "refactor the API layer"--model picks a gateway route (default, coder, fast). Requires the gateway
running (npm run gateway). Also settable via AGENT_GATEWAY and AGENT_GATEWAY_URL.
Run as a service (Docker)
docker build -t local-gateway .
docker run -d --name gateway -p 8787:8787 \
-e OPENROUTER_API_KEY=... -e GEMINI_API_KEY=... -e GROQ_API_KEY=... \
--restart unless-stopped local-gatewayKeys come from environment variables (.env is gitignored and not copied into the image).
Config is validated at startup — unknown provider types, missing models, and routes
that reference unknown providers print a warning.#� �O�p�e�n�-�A�I�-�P�r�o�j�e�c�t�
�
�
