BlackRiver Gateway by BlackRiver AI

The promise

One endpoint. Never stop building.

Routing

Stop hardcoding your AI stack.

BlackRiver Gateway gives teams one endpoint for many providers. Requests can be routed by cost, model capability, quota, latency, availability or internal policy.

When one provider fails, hits limits or becomes too expensive for the task, the gateway moves traffic — without forcing every tool to be reconfigured.

01

Subscription first

Use the accounts and subscriptions your team already pays for before sending traffic elsewhere.

02

Fallback routing

Move requests to alternative providers when rate limits, outages or quota exhaustion hit.

03

Cost control

Select models based on task value instead of always defaulting to premium endpoints.

Providers we route through

236 providers. One OpenAI-compatible endpoint.

From the largest commercial model APIs to free tiers, local models and self-hosted backends. New providers ship in days, not quarters.

OpenAI Anthropic Google Gemini Mistral OpenRouter Groq Cohere Together Fireworks Perplexity DeepSeek xAI Replicate Anyscale Lepton Novita DeepInfra AI21 Upstage Voyage Jina Cloudflare AI Cerebras NVIDIA NIM SambaNova Friendli Hyperbolic AIOZ Nebius Chutes Kluster Submodel Pollinations LongCat Kiro Antigravity Ollama LM Studio vLLM LocalAI + 196 more

Quickstart

Three commands. Zero config.

Step 1

Install & run

One command. The gateway starts on localhost with sensible defaults.

shell

$ npm i -g @blackriver/gateway
$ blackriver-gateway start
› listening on http://localhost:8080

Step 2

Connect a free provider

Paste a key or pick a free tier. Quota, cost and capability are detected automatically.

providers.env

# any of these, mixed together
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AIza...
OPENROUTER_API_KEY=sk-or-...

# or pick a free tier
FREE_PROVIDERS=pollinations,longcat

Step 3

Point your IDE

Set the base URL. Existing OpenAI clients work without code changes.

client.js

// any OpenAI-compatible tool
baseURL = "https://gateway.blackriver.ai/v1"
apiKey  = "br_..."

Features

Everything built in. No add-ons.

Tools

One config. Every coding tool works.

Point Claude Code, Codex, Cursor, Cline, OpenCode or any OpenAI-compatible client at the gateway. Routing, fallback and policy become a setting, not a refactor.

Why

Why BlackRiver Gateway

Compare

How we compare.

Capability	BlackRiver Gateway	LiteLLM	Portkey	OpenRouter
OpenAI-compatible endpoint	Yes	Yes	Yes	Yes
Self-hostable	Yes — local or remote	Yes	Cloud-first	No
Auto-fallback across providers	3-layer	Manual	Manual	Yes
Free-tier routing	90+ providers	No	No	Limited
MCP server (95 tools)	Yes	No	No	No
A2A protocol	Yes	No	No	No
Token compression	15–95%	No	No	No
Memory & skills	Built in	No	No	No
TokenOptimizer integration	Native	No	Webhook	No
Pricing model	Free self-host	Free self-host	Usage-based	Per-token

Architecture

One endpoint. Many decisions.

The gateway exposes an OpenAI-compatible API surface while routing traffic to multiple provider backends behind the scenes.

gateway.js

// any OpenAI-compatible client
const client = new OpenAI({
  baseURL: "https://gateway.blackriver.ai/v1",
  apiKey:  process.env.BLACKRIVER_GATEWAY_KEY,
});

const response = await client.chat.completions.create({
  model: "auto:code",
  messages: [{ role: "user", content: "Refactor this module" }],
});

// Gateway decides:
//   provider, model, fallback, quota, cost, policy.

Where it runs

Deploy anywhere your stack lives.

Combos

Auto-combo engine.

A single request can fan out across multiple models in parallel, get scored, deduplicated and merged. The gateway picks the answer that best fits the policy you defined — without your tool knowing.

Request

"Refactor this module"

Fan-out

3 models in parallel

Score

Best answer by policy

Claude Sonnet0.92

GPT-4o0.81

Gemini 1.5 Pro0.74

Result: Claude Sonnet wins on quality, but Gemini wins on cost — policy decides.

Free tier

~1.6B free tokens a month.

By combining free tiers across providers, the gateway exposes close to 1.6 billion free tokens every month — without spinning up a single paid account.

90+

Free-tier providers onboard by default.

11

Free-forever providers, no rate cliff.

1.6B

Combined free monthly tokens.

$0

Cost to start. Self-host forever.

Compression

Save 15–95% on tokens.

TokenOptimizer-aware compression runs at the gateway. System prompts, tool outputs and long contexts are rewritten before they leave — typically 60% on tool-heavy sessions, up to 95% on chatty ones.

Raw prompt 1,420 tokens

RTK compression 540 tokens (-62%)

+ Caveman rewrite 180 tokens (-87%)

Same task. Same model. Different bill. TokenOptimizer turns this into a measurable audit.

Resilience

3 layers of fallback. Zero downtime.

Layer 1 — Provider

Cross-provider

If a provider returns an error, hits a rate limit or times out, the gateway moves the request to the next configured provider in milliseconds.

Layer 2 — Model

Cross-model

If a specific model is degraded or removed, the gateway re-routes to the next model in the capability tier — without the client knowing.

Layer 3 — Account

Cross-account

If a subscription is exhausted, the gateway shifts traffic to another account, free tier or organization pool — also without the client knowing.

Proxy

3-level proxy. Stealth by default.

1 — Sticky

Sticky sessions

Pin a session, model or tool to a specific account or provider to preserve state and avoid context churn.

2 — Stealth

Stealth mode

Header rewriting, fingerprint rotation and traffic shaping keep sessions under the radar of aggressive rate limits.

3 — Private

Private & local-first

Run entirely on your own hardware, on your own VPC or on a single developer laptop. No telemetry, no lock-in.

Dashboard

A real dashboard. Not a config file.

Inspect traffic, replay requests, watch provider health, manage keys and audit every call. The gateway ships with a first-party UI — and a CLI for teams that prefer it.

Live traffic healthy

claude-sonnet → claude

last 1h · 1,284 req

p95 412ms

gpt-4o → openai

last 1h · 921 req

p95 380ms

gemini-1.5 → google

last 1h · 612 req

p95 290ms

glm-4.5 → zhipu

last 1h · 410 req

p95 540ms

Protocols

Connect an agent — it drives the gateway itself.

MCP

MCP server

95 Model Context Protocol tools exposed to agents. Inspect, replay, route, fallback, switch policy — all from inside the agent.

A2A

A2A server

Agent-to-agent handoff. External agents negotiate models, context and policy with the gateway directly over a typed protocol.

Cloud agents

Cloud-hosted agents can connect, register and use the gateway as a shared routing brain across the team.

Platform

Not just a proxy — a platform.

Services

Embedded services

Memory, cache, queue, scheduler and skills are embedded services — not external systems to wire up.

Context

Your knowledge, in context

Plug in documents, embeddings and indexes. The gateway injects the right context into the right model at the right time.

Safety

Guardrails built in

PII redaction, prompt guards and per-team policy live at the edge — not in every tool's prompt.

Engagement

Gamification

Surface provider health, savings and fallback wins to the team. Make routing decisions visible and rewarding.

Enterprise

From developer router to company control layer.

The same gateway a single developer installs in 30 seconds becomes the AI routing layer for the whole company — with policy, audit and observability in place.

Company

BlackRiver AI Ltd.

A UK company created to build, own and operate AI products and infrastructure. The gateway is one of its products.

ProductBlackRiver Gateway

OperatorBlackRiver AI Ltd

Company number17291854

JurisdictionEngland & Wales

BaseLondon, United Kingdom

Sister productTokenOptimizer

Contact

Build AI routing with BlackRiver AI.

Gateway deployment, provider routing, enterprise controls, private forks and integration with TokenOptimizer.

A note on lineage

BlackRiver Gateway is a BlackRiver AI product. The architecture, UX patterns and provider-fallback model draw from open-source AI router projects in the wider community. Original licenses, attribution and notices are preserved in the public repository and documentation.

One gateway. Every model.

Never hit limits

Save up to 95% on tokens

$0 to start

Every tool works

One endpoint, many decisions

Production-grade

Stop hardcoding your AI stack.

Subscription first

Fallback routing

Cost control

236 providers. One OpenAI-compatible endpoint.

Install & run

Connect a free provider

Point your IDE

Smart combos

Memory & skills

3-layer fallback

Free quota

Compression

MCP server

A2A protocol

17 routing strategies

One config. Every coding tool works.

Claude Code, Codex, Cursor

Cline, OpenCode, Roo

Copilot, Continue, Kiro

Antigravity, Kilocode

No vendor lock-in

Tools stay online

Cheaper by default

One endpoint. Many decisions.

Save 15–95% on tokens.

Cross-provider

Cross-model

Cross-account

Sticky sessions

Stealth mode

Private & local-first

Replay any request

Full event log

First-party CLI

MCP server

A2A server

Cloud agents

Embedded services

Your knowledge, in context

Guardrails built in

Gamification

From developer router to company control layer.

Policy-aware routing

Usage visibility

TokenOptimizer integration

Private forks & enterprise builds

BlackRiver AI Ltd.

Build AI routing with BlackRiver AI.

One gateway.
Every model.