Showdar Router：面向 OpenCode 的本地优先 AI 路由网关

Local-first AI routing gateway for OpenCode and OpenAI-compatible clients.

OpenAI-compatible · Health-aware routing · Ordered fallback · Local-first

Showdar Router gives your AI tools a single local endpoint for multiple providers, credentials, models, and fallback combinations.

Configure your providers once, create a direct model or combo, then point OpenCode or any compatible client at:

http://127.0.0.1:21298/v1

Quick Start

Install globally:

npm install -g showdar-router

Launch:

showdar-router

The interactive launcher lets you open the dashboard, use the terminal UI, or keep Showdar Router running from the system tray.

Default dashboard:

http://localhost:21298

Suggested free models are discovered dynamically from registered provider catalogs. Showdar Router contacts only those trusted catalog endpoints and caches successful discovery results briefly.

Instead of configuring every AI client against every provider separately:

flowchart LR
    A[OpenCode / AI Client] --> B[Showdar Router]

    B --> C[Direct Model]
    B --> D[Combo]

    D --> E[Model 1]
    D --> F[Model 2]
    D --> G[Model 3]

    C --> H[Providers]
    E --> H
    F --> H
    G --> H

Showdar Router acts as the local routing layer between your tools and upstream providers.

It provides:

One OpenAI-compatible local API.
Multiple providers and credentials.
Direct model routing.
Ordered model combos with fallback.
Health-aware cooldown and recovery.
Provider and account fallback where supported.
Retry and provider reset metadata handling.
Usage and quota visibility where available.
Web dashboard, CLI, terminal UI, and system tray.

Routing

Combo candidates preserve their configured order after routing eligibility is known. Requests with hard input requirements (vision, PDF, audio, or video) never fall back to a model that cannot receive that data; unavailable routes are then skipped using read-only health inspection followed by a single half-open acquisition at attempt time.

Round-robin combos rotate only among eligible candidates and keep the cursor stable when a route fails. Fusion uses a bounded panel (four concurrent calls by default), cancels stragglers after quorum, and reuses a lone successful panel response instead of making a duplicate provider call.

For example:

coding-fast

1. gemini/gemini-3.7-flash
2. gemini/gemini-3.6-flash
3. ollama/minimax-m3
4. nvidia/nemotron-3-ultra-550b-a55b
5. openrouter/...
6. opencode/...

If a route becomes temporarily unavailable:

flowchart TD
    A[Request] --> B{Route health}

    B -->|Healthy| C[Try route]
    B -->|Cooldown| D[Skip route]
    B -->|Half-open| E[Single probe]

    C --> F{Success?}
    E --> F

    F -->|Yes| G[Recover route]
    F -->|No| H[Classify failure]

    H --> I[Apply cooldown]
    I --> J[Next combo candidate]

    D --> J

Showdar Router can classify and recover from conditions such as:

quota exhaustion
subscription requirements
authentication failures
unsupported models
missing models
provider capacity
network failures
timeouts

Where available, provider recovery metadata such as Retry-After, retry delays, and reset timestamps is used instead of repeatedly probing a route that is known to be unavailable.

Showdar Router does not reorder combo candidates based on latency.

Port Selection

The default port is:

Normally:

Dashboard  http://localhost:21298
API        http://127.0.0.1:21298/v1

If the default port is already occupied and you did not explicitly select a port, Showdar Router automatically searches the next available port (up to 10 attempts).

Use --port or -p when you need a stable port:

showdar-router --port 30000

If 30000 is already occupied, startup fails:

Error: Port 30000 is already in use.

Showdar Router will not silently switch away from an explicitly requested port.

This prevents client configuration from unexpectedly pointing at the wrong endpoint.

OpenCode Setup

Start Showdar Router:

showdar-router

Configure at least one provider and model or combo from the dashboard.

Then configure your OpenAI-compatible client to use:

http://127.0.0.1:21298/v1

For example, if your combo is named:

coding-fast

use coding-fast as the model identifier from your client.

Router API key

Provider credentials and the Showdar Router client API key are separate concepts.

When Require API Key is disabled, trusted clients running locally can access the local LLM endpoint without a Showdar Router API key.

When Require API Key is enabled, clients must provide a valid Showdar Router key.

Example client options:

{
  "baseURL": "http://127.0.0.1:21298/v1",
  "apiKey": "sk-showdar-example"
}

Never commit real provider credentials or router API keys.

Interactive Launcher

Running:

showdar-router

from an interactive terminal opens the launcher:

╭─────────────────────────────────────────────╮
│ Showdar Router                              │
│ Server  http://localhost:21298              │
├─────────────────────────────────────────────┤
│ › Web UI                                    │
│   Terminal UI                               │
│   Hide to Tray                              │
│   Exit                                      │
╰─────────────────────────────────────────────╯

Available interfaces:

Web UI opens the dashboard in your browser.

Terminal UI opens the interactive CLI.

Hide to Tray keeps the supervisor running and attaches the system tray controller.

Exit closes the launcher and stops the server.

In non-interactive environments, running without arguments starts the supervisor directly.

CLI Options

showdar-router                    # Start with default settings
showdar-router --port 30000       # Custom port
showdar-router --no-browser       # Don't open browser
showdar-router --skip-update      # Skip auto-update check
showdar-router --tray             # Run in system tray mode (background)
showdar-router -t                 # Short alias for --tray
showdar-router --help             # Show all options
showdar-router --version          # Show version

Commands:

showdar-router xai video --prompt "..." --output video.mp4
                      Generate a Grok Imagine video via the running gateway
                      (see: showdar-router xai video --help)

System Tray

The tray is a control plane for the running Showdar Router supervisor.

It does not launch a second server.

Typical tray actions include:

Showdar Router
────────────────────
Running · :21298

Open Dashboard
Open Logs
Restart Server
Stop Server
────────────────────
Quit Tray

Quit Tray closes the tray icon and stops the supervisor and server.

Stop Server explicitly stops the server (the supervisor will not restart it).

Restart Server restarts the server while keeping the supervisor alive.

Dashboard

The dashboard provides configuration and visibility for the current Showdar Router runtime.

Main areas include:

Area	Purpose
Endpoint & Key	Local endpoint and client access
Providers	Provider connections and credentials
Combo & Vision Adapter	Model combinations and routing
Usage	Request and token usage
Quota Tracker	Provider quota information
Token Saver	Token optimization controls
CLI Tools	CLI integrations and configuration
Media Providers	Embedding, image, video, TTS, STT and web APIs
Proxy Pools	Proxy configuration
Console Log	Runtime logs
Settings	Router configuration

Availability depends on the provider and enabled features.

Health-Aware Recovery

Showdar Router keeps route health separate from credential/account health.

A route can transition through:

healthy
   │
   ▼
cooldown
   │
   ▼
half-open
   │
   ├── success ──► healthy
   │
   └── failure ──► cooldown

Only one half-open probe is allowed for a recovering route at a time.

When a provider returns an explicit recovery hint, Showdar Router can use information such as:

resetAt
resetsAt
Retry-After
retryDelay
retryAfter
X-RateLimit-Reset

before falling back to bounded internal cooldown behavior.

This avoids repeatedly calling providers that have already communicated when they will become available again.

Empty Response Fallback

An HTTP 200 response does not necessarily mean a usable chat completion was produced.

For streaming chat requests, a response with no meaningful content, reasoning, or tool frames can be treated as a failed route.

The combo may then continue to the next candidate instead of returning an empty successful response to the client.

Security

Showdar Router distinguishes trusted local requests from remote requests.

Disabling Require API Key is intended for trusted local access. It does not automatically make LAN, tunnel, reverse-proxy, or public traffic trusted.

Production requests pass through:

flowchart LR
    A[OpenCode / Client] --> B[Showdar Router daemon]
    B --> C[Trusted peer wrapper]
    C --> D[Next standalone server]
    D --> E[API / Dashboard]

The wrapper derives trusted local-peer information from the actual connection rather than blindly trusting client-supplied host or forwarding headers.

Spoofing headers such as a localhost host name or loopback forwarded address is not sufficient to gain trusted-local status.

For remote client access, enable Require API Key and configure network exposure deliberately.

Do not expose an unsecured Showdar Router API directly to the public internet.

Data & Runtime

Default data directory:

~/.showdar-router

Logs:

~/.showdar-router/logs/showdar-router.log

Development

Clone the repository:

git clone https://github.com/caongocquy/showdar-router.git
cd showdar-router

Install dependencies:

npm install

Run in development:

npm run dev

Build production assets:

npm run build

Install the local CLI from the checkout:

./scripts/install-local.sh

Then:

showdar-router

Docker is not required for the supported Showdar Router runtime.

Environment

Canonical Showdar Router environment variables include:

SHOWDAR_ROUTER_PORT
SHOWDAR_ROUTER_DATA_DIR

Defaults:

SHOWDAR_ROUTER_PORT=21298
SHOWDAR_ROUTER_DATA_DIR=~/.showdar-router

CLI arguments take precedence where applicable.

Testing

Run the focused routing release gate:

npm run test:routing

It covers the fork's critical routing behavior, including:

combo fallback
route health
recovery metadata
account/provider fallback
retry behavior
empty response handling

Run the production runtime smoke test:

npm run test:runtime

Build from a clean Next output:

rm -rf .next
npm run build

The inherited upstream broad test suite can also be run with:

npm test

The broad inherited suite is not represented as the primary Showdar Router release gate.

Supported Runtime

The primary user flow is:

npm install -g showdar-router
         │
         ▼
    showdar-router
         │
         ▼
  Supervisor (/ Launcher / Tray)
         │
         ▼
  Next standalone server
         │
         ▼
  OpenAI-compatible API

The supported distribution target is the local npm/CLI installation.

Upstream

Showdar Router originated as an independent fork of decolua/9router and is now maintained as its own product.

The project preserves upstream attribution and compatibility where appropriate while maintaining its own product identity, runtime, routing behavior, and release process.

Showdar Router is not affiliated with OpenAI, OpenCode, Anthropic, Google, NVIDIA, Ollama, OpenRouter, or other providers referenced by the project.

License

Licensed under the MIT License.

Showdar Router is based on the upstream project. Upstream copyright and license notices are preserved.