DEV Community

KALPESH
KALPESH

Posted on

Free Claude Code with Lynkr + Kilo Gateway

#ai #claude #cli #tutorial

Route Claude Code through Lynkr proxy → Kilo Gateway free models.

Zero Anthropic billing. Zero OpenRouter billing.

How it works 

Claude Code / Cursor / Codex / Cline / Continue                                         ← Your Prompt
        ↓
Lynkr (localhost:8081)                                                                  ← intercepts Anthropic-format request
        ↓
Ollama | Bedrock | Databricks | OpenRouter | Azure | OpenAI | llama.cpp | Kilo Gateway  ← routes to free model
        ↓
LLM response                                                                            ← streamed back to Claude Code
Enter fullscreen mode Exit fullscreen mode

ANTHROPIC_API_KEY is just a dummy value — Lynkr ignores it and uses your Kilo key internally.

Prerequisites

  • Node.js 20+ → check with node --version, install from nodejs.org
  • Linux / macOS / WSL (Windows works via WSL)

Step 1 — Get a Kilo Gateway API Key (Free)

  1. Go to app.kilo.ai and sign up (Google login works)
  2. Navigate to API Keys in the dashboard
  3. Click Generate API Key → copy it (a long JWT token)

Free models available on Kilo (no credit card needed):

Model ID Best for
kilo-auto/free Auto-picks best free model
nvidia/nemotron-3-super-120b-a12b:free Large, capable (120B)
arcee-ai/trinity-large-thinking:free Reasoning tasks
x-ai/grok-code-fast-1:optimized:free Coding tasks
openrouter/free OpenRouter's best free model

Step 2 — Install Claude Code CLI 

npm install -g @anthropic-ai/claude-code
claude --version   # verify
Enter fullscreen mode Exit fullscreen mode

Step 3 — Install Lynkr 

npm install -g pino-pretty
npm install -g lynkr
lynkr --version    # verify
Enter fullscreen mode Exit fullscreen mode

Step 4 — Create Lynkr config folder and .env 

mkdir ~/Desktop/lynkr && cd ~/Desktop/lynkr
nano .env
Enter fullscreen mode Exit fullscreen mode

Paste this into .env (replace YOUR_KILO_KEY with your actual key):

# ── Provider ──────────────────────────────────────────────────
MODEL_PROVIDER=openai

# ── Kilo Gateway (OpenAI-compatible) ──────────────────────────
OPENAI_API_KEY=YOUR_KILO_KEY_HERE
OPENAI_ENDPOINT=https://api.kilo.ai/api/gateway/chat/completions
OPENAI_MODEL=kilo-auto/free

# ── REQUIRED: All 4 tiers must be set (format = provider:model)
TIER_SIMPLE=openai:kilo-auto/free
TIER_MEDIUM=openai:kilo-auto/free
TIER_COMPLEX=openai:kilo-auto/free
TIER_REASONING=openai:kilo-auto/free

# ── Server ────────────────────────────────────────────────────
PORT=8081
NODE_ENV=development
LOG_LEVEL=info

# ── Disable features that need extra setup ────────────────────
SEMANTIC_CACHE_ENABLED=false # Caches similar prompts, needs an embeddings model configured
FALLBACK_ENABLED=false       # If Kilo fails, automatically retries with a backup provider
MEMORY_ENABLED=false         # Gives the AI persistent memory across sessions, needs extra DB/vector setup
HEADROOM_ENABLED=true        # Reserves token budget to avoid hitting context limits mid-conversation
AGENTS_ENABLED=true          # Enables Lynkr's built-in agent system (web search, code exec, etc.)
Enter fullscreen mode Exit fullscreen mode

Save and exit (Ctrl+O, Enter, Ctrl+X in nano).

Step 5 — Start Lynkr 

cd ~/Desktop/lynkr
lynkr start
Enter fullscreen mode Exit fullscreen mode

You'll see logs ending with:

Claude→Databricks proxy listening on http://localhost:8081
Config watcher started ...
Enter fullscreen mode Exit fullscreen mode

The "Databricks" label is just a hardcoded display string in Lynkr's source — it doesn't mean it's routing to Databricks. Your .env controls the actual provider.

Leave this terminal running.

Step 6 — Verify it works (new terminal) 

curl -X POST http://localhost:8081/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: dummy" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 50,
    "messages": [{"role": "user", "content": "say hi"}]
  }'
Enter fullscreen mode Exit fullscreen mode

Expected response:

{
  "content": [{"type": "text", "text": "Hi there! How can I help you today?"}],
  "_routingMeta": {
    "provider": "openai",
    "model": "kilo-auto/free",
    "tier": "SIMPLE"
  }
}
Enter fullscreen mode Exit fullscreen mode

If you see _routingMeta with "model": "kilo-auto/free" — everything is working. ✅

Step 7 — Connect Claude Code to Lynkr 

export ANTHROPIC_BASE_URL=http://localhost:8081
export ANTHROPIC_API_KEY=dummy

claude "say hello"
Enter fullscreen mode Exit fullscreen mode

ANTHROPIC_API_KEY=dummy works because Lynkr ignores whatever value Claude Code sends — it uses your Kilo key from .env for all actual API calls.

Step 8 — Make it permanent

Add to your ~/.zshrc or ~/.bashrc:

# Lynkr / Claude Code proxy
export ANTHROPIC_BASE_URL=http://localhost:8081
export ANTHROPIC_API_KEY=dummy

# Quick start alias
alias lynkr-start="cd ~/Desktop/lynkr && lynkr start"
Enter fullscreen mode Exit fullscreen mode

Reload:

source ~/.bashrc   # or source ~/.zshrc
Enter fullscreen mode Exit fullscreen mode

Now every session:

  • Terminal 1: lynkr-start
  • Terminal 2: claude "anything" — free, forever

Step 9 — VS Code Claude Code Extension

The VS Code extension launches the Claude Code CLI in its own managed environment — it does not inherit export variables you set in your terminal. So even if your terminal has ANTHROPIC_BASE_URL set, the extension won't see it unless you configure it system-wide.

VS Code Extension
      ↓
  launches CLI internally
      ↓
  CLI checks → ANTHROPIC_API_KEY env var   ← terminal exports don't reach here
                     OR
               ~/.claude/credentials       ← extension's own auth storage
Enter fullscreen mode Exit fullscreen mode

Option A — Set it in VS Code settings (per-user)

Open VS Code → Ctrl+, → search terminal env → click Edit in settings.json and add:

"terminal.integrated.env.linux": {
  "ANTHROPIC_BASE_URL": "http://localhost:8081",
  "ANTHROPIC_API_KEY": "dummy"
}
Enter fullscreen mode Exit fullscreen mode

Use "terminal.integrated.env.osx" on Mac, "terminal.integrated.env.windows" on Windows.

Restart VS Code after saving.

Option B — Set it system-wide in /etc/environment (recommended)

This makes the env vars available to every app on your system — VS Code, terminals, everything — without any per-app config.

sudo nano /etc/environment
Enter fullscreen mode Exit fullscreen mode

Add these two lines at the end:

ANTHROPIC_BASE_URL=http://localhost:8081
ANTHROPIC_API_KEY=dummy
Enter fullscreen mode Exit fullscreen mode

Save (Ctrl+O, Enter, Ctrl+X), then log out and log back in (or reboot).

Verify it worked:

printenv ANTHROPIC_BASE_URL   # should print http://localhost:8081
Enter fullscreen mode Exit fullscreen mode

Workflow with VS Code extension

  1. Terminal 1: lynkr-start (keep running)
  2. Open VS Code → Claude Code extension → it now routes through Lynkr automatically ✅ > The extension may still show "Claude Sonnet 4.6" as the model name — that's normal. Lynkr returns that label to satisfy the extension's auth check. Your actual model is kilo-auto/free running on Kilo Gateway.

Troubleshooting

Problem Fix
[WARN] Missing tier configuration All 4 TIER_* vars must be set in .env
is not a valid model ID Remove kilo/ prefix — correct format is kilo-auto/free not kilo/kilo-auto/free
Connection refused Lynkr isn't running — start it first
Claude→Databricks in logs Normal — just a hardcoded label, doesn't affect routing
Model says "Claude Sonnet 4.6" Normal — Lynkr returns a fake model name to satisfy Claude Code; real model is in _routingMeta
Slow first response Free-tier cold start — second request is faster

Reference: Lynkr GitHub

Top comments (0)