# openrouterX

openrouterX is a local AI provider router and management dashboard for coding
agents and AI developer tools.

It exposes OpenAI-compatible, Anthropic-compatible, Gemini-compatible, and
provider-scoped endpoints, then routes requests to the provider accounts you
connect in the dashboard. It is designed for local and self-hosted workflows
where you want one endpoint, many provider accounts, quota visibility, and
predictable fallback behavior.

[npm package](https://www.npmjs.com/package/@yina-npm/openrouterx)

## Install

```bash
npm install -g @yina-npm/openrouterx
openrouterX
```

The dashboard starts on:

```text
http://localhost:20502/dashboard
```

Useful commands:

```bash
openrouterX --version
openrouterX status
openrouterX restart --skip-update
openrouterX stop
```

Runtime data is stored outside the package:

```text
macOS/Linux: ~/.openrouterx
Windows:     %APPDATA%/openrouterx
```

## What It Does

- One local endpoint for coding tools such as Claude Code, OpenAI Codex,
  GitHub Copilot, Gemini CLI, OpenCode, Cline, Kilo Code, and compatible tools.
- Dashboard-based provider and account management.
- OAuth and API-key providers, including subscription-style provider accounts.
- Multi-account routing with per-provider fallback and round-robin strategies.
- Quota and usage views for supported providers.
- Sub-user accounts with provider/account-level access control.
- Provider-scoped OpenAI-compatible routes, for example
  `/api/v1/providers/codex/chat/completions`.
- MITM helpers for supported local tooling workflows.
- Packaged standalone Next.js runtime for global npm installation.

## Default Endpoint

Use the local OpenAI-compatible endpoint with your tools:

```text
http://localhost:20502/api/v1
```

Common examples:

```text
http://localhost:20502/api/v1/chat/completions
http://localhost:20502/api/v1/responses
http://localhost:20502/api/v1/embeddings
http://localhost:20502/api/v1/images/generations
```

For tools that expect `/v1`, openrouterX also exposes:

```text
http://localhost:20502/v1
```

## Model Names

Model aliases are managed in the dashboard. Typical provider-prefixed model
names look like:

```text
codex/gpt-5.5
codex/gpt-5.3-codex
github/gpt-5.3-codex
claude/claude-opus-4-5
gemini/gemini-3-pro
```

Auto routes and custom combos can be configured in the dashboard when you want
fallback across multiple providers.

## API Keys And Users

For local-only use, the dashboard can run with relaxed local defaults. For
shared or remote deployments, create API keys in the dashboard and assign them
carefully:

- Super admin keys are unassigned keys.
- Sub-user keys are bound to a specific sub-user.
- Sub-users can be limited to specific providers and specific provider
  connection IDs.

## Updating

```bash
npm install -g @yina-npm/openrouterx@latest --prefer-online
openrouterX restart --skip-update
```

## Uninstall

```bash
npm uninstall -g @yina-npm/openrouterx
```

This removes the npm package. Runtime data under `~/.openrouterx` is not removed
automatically.

## Local Development

```bash
npm install
npm run dev
```

Build:

```bash
npm run build
```

Create and validate the npm staging package without publishing:

```bash
npm run release:npm:dry
```

Install a local test build globally:

```bash
npm run release:npm:install-local
```

## Package

Published package:

```text
@yina-npm/openrouterx
```

Global command:

```text
openrouterX
```

Default port:

```text
20502
```
