ineedrouter

iNeedRouter

A focused AI gateway for teams that want one reliable endpoint.

Route OpenAI- and Anthropic-shaped requests across 40+ providers, keep credentials in one operator console, and let fallback policies handle upstream variance.

Documentation · Contribute · Report an issue

iNeedRouter is a maintained fork of 9router (MIT). It preserves the upstream routing surface while adding iNeed branding, operator workflows, and selected routing improvements inspired by OmniRoute and ZRouter.

Highlights

• Three interface languages — switch freely between Indonesian, English, and Simplified Chinese; your choice is persisted on the device.
• One endpoint, many providers — POST /v1/chat/completions (OpenAI format), POST /v1/messages (Anthropic format), plus image, TTS, STT, embeddings, web search, web fetch, and video generation.
• Automatic fallback — model combos and multi-account fallback keep requests alive when an upstream fails.
• Format translation — requests pivot through OpenAI as the intermediate format, with direct routes for fragile pairs (thinking blocks, tool IDs, protobuf upstreams).
• OAuth + API key credentials — token refresh, quota tracking, and per-account management built in.
• Operator dashboard — providers, combos, keys, usage analytics, routing policies, CLI-tool one-click setup, agent skills, and more.
• Token saver (RTK) — pre-translate hooks compress large tool_result payloads to cut token spend; fail-open by design.
• iNeed design system — the lavender/indigo/emerald editorial UI from ineed.web.id.

Architecture

Client / SDK
    │ OpenAI or Anthropic request
    ▼
Gateway endpoint ──► format translation ──► provider + account pool ──► upstream API
        │                    │                         │
        └── usage + keys     └── fallback + routing    └── OAuth / API key auth

The operator console owns configuration and observability; the request path stays compatible with standard OpenAI and Anthropic clients.

Contributing

1. Fork the repository and create a focused branch.
2. Run npm install, then npm run build before opening a pull request.
3. Add focused tests for behavior changes and keep credentials out of commits.
4. Explain the user-facing effect and verification steps in the pull request.

Quick start (source)

cp .env.example .env
npm install
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev    # dev
npm run build && PORT=20128 HOSTNAME=0.0.0.0 npm run start            # production

Dashboard: http://localhost:20128/dashboard — set INITIAL_PASSWORD explicitly before exposing the dashboard.

Endpoint: http://localhost:20128/v1/...

Quick start (Docker)

cp .env.example .env
docker compose up -d        # builds the image from source

Data lives in the ineedrouter-data volume (DATA_DIR=/app/data). See DOCKER.md.

CLI launcher

npm install -g ineedrouter   # after publishing, or use npx from a checkout
ineedrouter

The CLI starts the server in the background, manages the system tray, and keeps the runtime self-healing. The app dashboard's "Check for updates" flow updates from this repository.

Agent skills

Copy-paste skill files let any AI agent use the gateway directly — chat, image, TTS, STT, embeddings, video, web search, web fetch. Open Dashboard → Skills for the raw URLs, or browse skills/.

Data & persistence

State is SQLite (driver chain: bun:sqlite → better-sqlite3 → node:sqlite → sql.js fallback). The data directory resolves via DATA_DIR, defaulting to ~/.9router for compatibility with existing installations.

Security

• Derives client IP from the TCP socket; X-Forwarded-For is trusted only from a loopback reverse proxy.
• Sensitive env: JWT_SECRET, INITIAL_PASSWORD, API_KEY_SECRET, and MACHINE_ID_SALT. Set INITIAL_PASSWORD explicitly before exposing the dashboard. See .env.example for the full contract.

Documentation

• DOCKER.md — Docker deployment
• docs/ARCHITECTURE.md — request lifecycle, fallback, OAuth, data model
• CHANGELOG.md — release history (upstream history preserved)

License

MIT — inherits 9router by decolua and contributors.