DEV Community

KALPESH
KALPESH

Posted on

CCR + Kilo Gateway — Full Setup Guide

#ai #claude #cli #tutorial

Use Claude Code (terminal + VS Code extension) free via Kilo Gateway's kilo-auto/free model, routed through Claude Code Router (CCR).

Prerequisites

  • Node.js installed (node -v to verify)
  • npm available
  • A terminal

Step 1 — Get Kilo Gateway API Key

  1. Go to app.kilo.ai → sign up / sign in
  2. Navigate to API Keys → generate a new key
  3. Copy it — needed in Step 4

Step 2 — Install Claude Code 

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

Step 3 — Install CCR 

npm install -g @musistudio/claude-code-router
Enter fullscreen mode Exit fullscreen mode

Verify:

ccr --version
Enter fullscreen mode Exit fullscreen mode

Step 4 — Create CCR config

CCR always reads from ~/.claude-code-router/config.json. No env var or flag overrides this.

mkdir -p ~/.claude-code-router
Enter fullscreen mode Exit fullscreen mode 
cat > ~/.claude-code-router/config.json << 'EOF'
{
  "LOG": true,
  "Providers": [
    {
      "name": "kilogateway",
      "api_base_url": "https://api.kilo.ai/api/gateway/chat/completions",
      "api_key": "YOUR_KILO_API_KEY_HERE",
      "models": ["kilo-auto/free"]
    }
  ],
  "Router": {
    "default": "kilogateway,kilo-auto/free",
    "background": "kilogateway,kilo-auto/free",
    "think": "kilogateway,kilo-auto/free",
    "longContext": "kilogateway,kilo-auto/free"
  }
}
EOF
Enter fullscreen mode Exit fullscreen mode

Replace YOUR_KILO_API_KEY_HERE with your actual Kilo API key.

Step 5 — Configure VS Code extension (Optional)

The VS Code extension reads from ~/.claude/settings.json — this is separate from CCR's config.

mkdir -p ~/.claude
Enter fullscreen mode Exit fullscreen mode 
cat > ~/.claude/settings.json << 'EOF'
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:3456",
    "ANTHROPIC_AUTH_TOKEN": "dummy"
  }
}
EOF
Enter fullscreen mode Exit fullscreen mode

Then disable the login prompt in VS Code:

  1. Open VS Code → Ctrl+, (Settings)
  2. Search: claude code login
  3. Check ✅ Disable Login Prompt

Or add directly to your VS Code settings.json (Ctrl+Shift+P → Open User Settings JSON):

"claudeCode.disableLoginPrompt": true
Enter fullscreen mode Exit fullscreen mode

Step 6 — Start CCR manually (every time)

Every time you open a new terminal, run this once before using Claude Code:

ccr start
Enter fullscreen mode Exit fullscreen mode

Expected output:

Loaded JSON config from: /home/<user>/.claude-code-router/config.json
Providers configured: kilogateway
Listening on 127.0.0.1:3456
Enter fullscreen mode Exit fullscreen mode

ccr start runs as a background daemon — it will continue running after the command exits. You only need to start it once per session (until you reboot or stop it manually with ccr stop).

If you see "No providers configured" → your config.json is missing or has invalid JSON. Re-check Step 4.

When is ccr start required?

Scenario Need to run ccr start? Notes
Fresh terminal session (new shell) ✅ Yes Before using claude or ccr code
After system reboot ✅ Yes Daemon doesn't persist across reboots
After ccr stop ✅ Yes Must restart to use Claude Code again
After ccr restart ❌ No Already handled by the command
Same terminal after previous ccr start ❌ No Daemon is still running
VS Code reload (after initial setup) ❌ No Daemon persists independently
After editing config.json ⚠️ No Use ccr restart instead

Step 7 — Use it

Terminal:

ccr code
Enter fullscreen mode Exit fullscreen mode

VS Code extension:

Reload VS Code: Ctrl+Shift+P → Developer: Reload Window

The extension will skip the login screen and route through CCR → Kilo Gateway automatically.

Verify inside Claude Code:

/status
Enter fullscreen mode Exit fullscreen mode

Look for:

API Base URL: http://127.0.0.1:3456
Enter fullscreen mode Exit fullscreen mode

Step 8 — Persist CCR start via .bashrc (optional)

Don't want to run ccr start manually every session? Add it to ~/.bashrc so it auto-starts on every new terminal.

cat >> ~/.bashrc << 'EOF'

# Auto-start CCR and activate routing on new terminal
ccr start 2>/dev/null
eval "$(ccr activate)"
EOF
Enter fullscreen mode Exit fullscreen mode

Apply immediately:

source ~/.bashrc
Enter fullscreen mode Exit fullscreen mode

From now on, every new terminal will auto-start CCR and the claude command routes through CCR — no manual steps needed.

After editing config — always restart 

ccr restart
Enter fullscreen mode Exit fullscreen mode

Free models on Kilo Gateway

Model ID Description
kilo-auto/free Auto-picks best free model per session ✅ recommended
openrouter/free Best available free model via OpenRouter
x-ai/grok-code-fast-1:optimized:free xAI Grok, code-focused
bytedance-seed/dola-seed-2.0-pro:free ByteDance Dola Seed 2.0 Pro

Switch model mid-session:

/model kilogateway,openrouter/free
Enter fullscreen mode Exit fullscreen mode

Useful CCR commands

Command What it does
ccr start Start the router
ccr stop Stop the router
ccr restart Restart after config changes
ccr status Check if running
ccr code Launch Claude Code via router
ccr activate Print env vars for shell integration
ccr ui Open Web UI

File reference

File Path
CCR config ~/.claude-code-router/config.json
Desktop copy (if symlinked) ~/Desktop/ccr/config.json
Claude Code / VS Code settings ~/.claude/settings.json
Shell config ~/.bashrc
CCR logs ~/.claude-code-router/logs/
Router endpoint http://127.0.0.1:3456

Troubleshooting

VS Code shows login screen
→ Confirm ~/.claude/settings.json has ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN set, and claudeCode.disableLoginPrompt is true in VS Code settings. Then reload: Ctrl+Shift+P → Developer: Reload Window.

No providers configured on ccr start
→ Check ~/.claude-code-router/config.json exists and has valid JSON with a Providers array containing your Kilo API key.

Model not responding
→ Confirm your Kilo API key is valid at app.kilo.ai. Free tier is rate-limited to 200 req/hr per IP.

Config changes not taking effect
→ Always run ccr restart after editing config.json.

Auth conflict warning in Claude Code
→ Run claude /logout to clear stored Anthropic credentials, then use ccr code only.

Reference: CCR GitHub Link

Top comments (0)