# How to Integrate OmniRoute with Existing Node.js Projects

> Easily integrate OmniRoute with your Node.js projects. This OpenAI-compatible proxy routes AI requests to multiple providers without code changes. Get started today!

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-17

---

**OmniRoute is a self-hosted OpenAI-compatible proxy that runs on localhost:20128, allowing any Node.js application to route AI requests through multiple providers using standard HTTP clients or the official OpenAI SDK without code changes beyond the endpoint URL.**

OmniRoute provides a **self-hosted proxy/router** that exposes a single OpenAI-compatible HTTP API, making it trivial to integrate with existing Node.js codebases. Because it mimics the OpenAI API contract exactly, you can point any standard HTTP client—or the official `openai` SDK—at your local OmniRoute instance and immediately gain access to 340+ providers with automatic failover and token compression.

## Quick Start: Running OmniRoute Locally

Integration requires only two steps: install the CLI globally and start the server.

```bash
npm i -g omniroute
npx omniroute

```

By default, the server listens on `http://localhost:20128`. Once running, any Node.js process can send requests to `http://localhost:20128/v1/chat/completions`. No SDK installation is required in your project.

## Integration Methods for Node.js

Because OmniRoute exposes an OpenAI-compatible interface, you can integrate it using any HTTP library or the official SDK. Below are three common approaches.

### Using Axios (Non-Streaming)

The simplest approach uses any HTTP client like Axios. This example from [[`examples/quickstart/nodejs_axios.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/examples/quickstart/nodejs_axios.js)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/examples/quickstart/nodejs_axios.js) demonstrates a standard POST request:

```javascript
const axios = require('axios');

const API_URL = 'http://localhost:20128/v1/chat/completions';
const headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer dummy-key', // Any string works for free providers
};

const data = {
  model: 'felo/auto',      // Key-less free backend
  stream: false,
  messages: [{ role: 'user', content: 'Hello! What can you do?' }],
};

axios.post(API_URL, data, { headers })
  .then(res => console.log(res.data.choices[0].message.content))
  .catch(err => {
    console.error('Error:', err.message);
    if (err.response) console.error('Server replied:', err.response.data);
  });

```

**Note:** The `Authorization` header is required by the API contract but accepts any dummy value when using zero-config free providers.

### Using Native Fetch with Streaming (SSE)

Node.js 22+ includes global `fetch`, enabling Server-Sent Events (SSE) streaming without external dependencies:

```javascript
const API_URL = 'http://localhost:20128/v1/chat/completions';
const body = {
  model: 'auto',
  stream: true,
  messages: [{ role: 'user', content: 'Explain the difference between promises and callbacks.' }],
};

fetch(API_URL, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer dummy-key',
    'Accept': 'text/event-stream',
  },
  body: JSON.stringify(body),
})
  .then(res => {
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    const reader = res.body.getReader();
    const decoder = new TextDecoder();
    
    async function read() {
      const { value, done } = await reader.read();
      if (done) return;
      process.stdout.write(decoder.decode(value));
      await read();
    }
    return read();
  })
  .catch(console.error);

```

The server routes streaming requests through the early-keepalive wrapper defined in [[`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/app/api/v1/chat/completions/route.ts), ensuring clients receive standard OpenAI SSE events.

### Using the Official OpenAI SDK

For existing projects already using the OpenAI SDK, integration requires only changing the `baseURL`:

```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:20128/v1', // Point to OmniRoute
  apiKey: 'dummy-key',                  // Required but unused for free backends
});

const chat = await client.chat.completions.create({
  model: 'auto/coding', // Quality-first combo for code generation
  messages: [{ role: 'user', content: 'Write a quick sort in JavaScript.' }],
});

console.log(chat.choices[0].message.content);

```

The SDK sends a standard `POST /v1/chat/completions` request, which OmniRoute processes through the same route implementation used by raw HTTP clients.

## How Requests Are Processed Internally

When your Node.js code hits `http://localhost:20128/v1/chat/completions`, OmniRoute executes a multi-stage pipeline defined in the source code:

1. **Request Validation:** The payload is validated against a Zod schema in [[`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/app/api/v1/chat/completions/route.ts), ensuring OpenAI API compatibility.
2. **Guardrails:** Prompt-injection detection, admission-queue logic, and optional compression headers are applied immediately.
3. **Translation:** The `initTranslators` function in [[`open-sse/translator/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/translator/index.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/translator/index.ts) converts OpenAI-style payloads to the internal routing format.
4. **Routing:** The **Auto-Combo** engine selects the optimal provider based on quota, latency, and cost constraints, leveraging strategies defined in [[`src/sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/handlers/chat.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/sse/handlers/chat.ts).
5. **Resilience:** Circuit breakers ([[`src/open-sse/services/circuitBreaker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/open-sse/services/circuitBreaker.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/open-sse/services/circuitBreaker.ts)) and account-level cooldowns ([[`src/open-sse/services/accountFallback.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/open-sse/services/accountFallback.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/open-sse/services/accountFallback.ts)) prevent cascading failures.
6. **Response:** The result streams back as SSE or JSON, matching the OpenAI spec exactly.

## Features You Gain Automatically

By routing through OmniRoute instead of calling providers directly, existing Node.js projects instantly benefit from:

- **Zero-Config Free Providers:** Use `model: "felo/auto"` without API keys.
- **Automatic Fallback:** Access to 341 providers across 19 routing strategies.
- **Token Compression:** RTK and Caveman compression algorithms reduce token counts by 15-95%.
- **Built-in Guardrails:** Prompt-injection detection, rate-limit handling, and circuit breakers operate transparently.

## Summary

- **OmniRoute** exposes an OpenAI-compatible API at `localhost:20128`, requiring no SDK changes in your Node.js project.
- **Three integration methods** work out of the box: raw HTTP (Axios/fetch), native Node.js fetch with streaming, and the official OpenAI SDK via `baseURL` configuration.
- **Internal routing** occurs through [[`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/app/api/v1/chat/completions/route.ts) and [[`open-sse/translator/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/translator/index.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/translator/index.ts), providing automatic failover and compression.
- **Installation** requires only `npm i -g omniroute` and `npx omniroute` to begin accepting requests.

## Frequently Asked Questions

### Do I need to modify my existing OpenAI SDK code to use OmniRoute?

No. You only need to change the `baseURL` to `http://localhost:20128/v1` and provide any dummy API key. All existing method calls like `client.chat.completions.create()` function identically because OmniRoute mirrors the OpenAI API contract exactly, including SSE streaming formats.

### What Node.js versions support the streaming fetch example?

The native streaming example requires **Node.js 22 or higher**, which includes global `fetch` and `ReadableStream` support. For older versions, use the Axios example or install the `node-fetch` package. Both approaches work with OmniRoute's standard HTTP interface.

### How does authentication work when using free providers?

OmniRoute accepts any string in the `Authorization` header (e.g., `Bearer dummy-key`) when routing to free providers. The [[`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/app/api/v1/chat/completions/route.ts) implementation validates the header format but ignores the token value for key-less backends like `felo/auto`.

### Can I integrate OmniRoute into a production Node.js application?

Yes. The [[`src/open-sse/services/circuitBreaker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/open-sse/services/circuitBreaker.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/open-sse/services/circuitBreaker.ts) and [[`src/open-sse/services/accountFallback.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/open-sse/services/accountFallback.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/open-sse/services/accountFallback.ts) services provide production-grade resilience through provider-level circuit breakers and automatic cooldowns for rate-limited accounts. Run OmniRoute as a persistent service or container alongside your Node.js application.