JSPM

English | 한국어

Free model router CLI - discover, ping, and configure free AI models for OpenCode / OpenClaw.

Install

npx @bytonylee/free-router
# or
npm i -g @bytonylee/free-router
# or
bunx @bytonylee/free-router
# or
bun install -g @bytonylee/free-router

Run

free-router

On first run, a setup wizard prompts for API keys (ESC to skip any provider).

If you accept the in-app update prompt (Y), free-router now updates globally and restarts automatically, so you can continue without running free-router again.

Ways to use free-router

1. First-run onboarding wizard Launch free-router, open provider websites in-browser from the wizard, paste keys, and start.
2. Interactive model search + launch Use / to filter models, then Enter to update OpenCode config and open opencode.
3. Quick API key rescue from main screen Press A (or R for expired/missing provider) to jump into key editing with auto browser opening for missing keys.
4. Full settings workflow Press P to edit keys, toggle providers, run live key tests, and onboard missing keys provider-by-provider.
5. Non-interactive best-model selection Run free-router --best to print the best responding model ID for scripts.

Providers

API key priority: environment variable → ~/.free-router.json → keyless ping (latency still shown).

NVIDIA_API_KEY=nvapi-xxx free-router
OPENROUTER_API_KEY=sk-or-xxx free-router

# Optional: pause auto re-sorting while you scroll (milliseconds)
FREE_ROUTER_SCROLL_SORT_PAUSE_MS=2500 free-router

# Optional: disable rolling metrics cache and force legacy recompute path
FREE_ROUTER_METRICS_CACHE=0 free-router

TUI

The interactive TUI pings all models in parallel every 2 seconds and shows live latency, uptime, and verdict. The selected row uses a stable marker, and redraws are deferred while the terminal is unfocused to avoid background-tab blinking.

Columns

Default ranking: availability first, then higher tier first (S+ → S → A+ …), then lower latency.

Search bar provider badges:

• Name:✓ key exists and looks healthy
• Name:✗ provider appears expired/no-auth
• Name:○ key missing

The ? help overlay and A API-key editor use the same terminal header/footer chrome as the main list. Their mode tags stay left-aligned, and help body text uses the same foreground color as the table rows.

Keyboard shortcuts

Navigation

Actions

Sort (press to sort, press again to reverse)

OpenCode handoff

Pressing Enter on a model writes the OpenCode config and immediately opens opencode.

If OpenCode fallback remaps the provider (for example NIM Stepfun → OpenRouter) and the effective provider key is missing, free-router asks: Add API key now? (Y/n, default: Y).

If model metadata says the selected model is unsupported by the known target support list, free-router falls back to NVIDIA NIM deepseek-ai/deepseek-v4-pro as the default high-performance model.

Configs written:

• OpenCode CLI → ~/.config/opencode/opencode.json
• OpenClaw → ~/.openclaw/openclaw.json

Existing configs are backed up before writing.

When free-router launches OpenCode, it now sets OPENCODE_CLI_RUN_MODE=true by default (unless you already set it) to reduce startup log noise from plugin auto-update checks in the OpenCode TUI.

If you want OpenCode's default startup hook behavior instead, launch free-router with:

OPENCODE_CLI_RUN_MODE=false free-router

Settings screen (P)

Tip: press A from the main list to jump directly into API key editing. Tip: if a selected provider has no key, free-router auto-opens that provider key page in browser (once per provider per settings session), including when you move selection.

Flags

--best scripted usage

# Print best model ID after ~10 s analysis
free-router --best

# Capture in a variable
MODEL=$(free-router --best)
echo "Best model: $MODEL"

Requires at least one API key to be configured. Selection tri-key sort: status=up → lowest avg latency → highest uptime.

Config

Stored at ~/.free-router.json (permissions 0600).

{
  "apiKeys": {
    "nvidia": "nvapi-xxx",
    "openrouter": "sk-or-xxx"
  },
  "providers": {
    "nvidia": { "enabled": true },
    "openrouter": { "enabled": true }
  },
  "ui": {
    "scrollSortPauseMs": 1500
  }
}

ui.scrollSortPauseMs sets how long (ms) auto re-sorting stays paused after navigation input. FREE_ROUTER_SCROLL_SORT_PAUSE_MS overrides config. Set to 0 to disable pause.

Tier scale (SWE-bench Verified)

Verdict legend

Development notes

• TypeScript source of truth: src/
• ESLint config is TypeScript: eslint.config.ts
• Runtime JS output is generated only in dist/ via npm run build

License

MIT License. See LICENSE.