# Where Is the Main Entry Point for the OmniRoute Application?

> Discover the main entry point for the OmniRoute application. Learn how to launch the Next.js 15 runtime via npm scripts or the CLI using src/cli.ts.

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

---

**The main entry point for OmniRoute is the Next.js 15 runtime, launched via npm scripts in [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json), which loads API routes from `src/app/`. For CLI usage, the chain starts at [`src/cli.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/cli.ts) and delegates to [`src/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server.ts).**

OmniRoute is a Next.js App Router application that exposes LLM-compatible API endpoints. Understanding its startup chain is essential for debugging, custom deployments, and extending the system. This guide breaks down exactly how the application boots, which files control execution, and how the CLI and server modes differ.

---

## How OmniRoute Starts: The Next.js Runtime

The **primary entry point** for OmniRoute is not a single JavaScript file you execute directly. Instead, it follows standard Next.js conventions: the **Next.js CLI** serves as the bootstrapper.

In [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json), the relevant scripts are:

```json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

```

These invoke the Next.js runtime, which then:

1. Reads [`next.config.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/next.config.js) for configuration
2. Compiles or loads the application from `src/app/`
3. Mounts API routes under `src/app/api/v1/`
4. Starts the HTTP server on the configured port

The **default port is 20128**, though this can be overridden via environment variables or CLI flags.

---

## Server Mode Entry Point: [`src/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server.ts)

When OmniRoute runs as a standalone server—either through the CLI or programmatically—the critical file is **[`src/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server.ts)**. This module creates the raw HTTP server, applies middleware, and integrates the Next.js request handler.

Key responsibilities of [`src/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server.ts):

- Initializes the HTTP server using Node's `http` or `https` modules
- Applies CORS, logging, and error-handling middleware
- Mounts the Next.js request handler via `next({ dev: false }).getRequestHandler()`
- Listens on port **20128**

The file acts as a thin wrapper that lets OmniRoute run outside Next.js's built-in server when needed.

---

## CLI Entry Point: [`src/cli.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/cli.ts)

For command-line usage, the entry point shifts to **[`src/cli.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/cli.ts)**. This module parses arguments, loads configuration, and orchestrates startup.

Typical invocation flow:

```bash

# Via npx or global install

omniroute --port 3000 --mcp

```

What happens internally:

1. **[`src/cli.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/cli.ts)** parses flags using a CLI parser (likely `commander` or similar)
2. Loads environment configuration and validates inputs
3. Imports [`src/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server.ts) and calls its startup function
4. Optionally starts the **MCP server** if `--mcp` is passed

The CLI path ensures OmniRoute can run as a system service or containerized binary without requiring `next` commands.

---

## API Route Layer: `src/app/api/v1/`

Once the server is running, **actual request handling** enters through Next.js App Router routes. The core LLM endpoint is:

```

src/app/api/v1/chat/completions/route.ts

```

This file implements the OpenAI-compatible `/v1/chat/completions` endpoint. It delegates to:

- **[`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts)** — Core routing logic for LLM requests, model selection, and streaming response generation

Other API routes in `src/app/api/v1/` handle:
- Model listing (`/models`)
- Embeddings (`/embeddings`)
- Health checks and metadata

---

## Optional MCP Server Entry Point

When OmniRoute runs with **Model Context Protocol (MCP)** support enabled, an additional entry point activates:

- **[`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts)**

This starts a separate server—or attaches to the main server—that exposes tools via the MCP specification. It is triggered by:

```bash
omniroute --mcp

# or

npm run start -- --mcp

```

The MCP server runs alongside the main HTTP server, not as a replacement.

---

## Startup Chain Summary

| Stage | Entry File | Role |
|-------|-----------|------|
| npm script | [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json) | Invokes `next dev` or `next start` |
| Next.js runtime | (internal) | Loads `src/app/` and compiles routes |
| API request | `src/app/api/v1/*/route.ts` | Receives HTTP requests |
| Core handler | [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts) | Processes LLM routing logic |
| CLI bootstrap | [`src/cli.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/cli.ts) | Parses args, loads config |
| Server creation | [`src/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server.ts) | Creates HTTP server on port 20128 |
| MCP mode | [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) | Optional tool server |

---

## Summary

- **Standard deployment**: Run `npm run dev` or `npm start` → Next.js boots → loads `src/app/` → API routes handle requests
- **CLI/programmatic usage**: [`src/cli.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/cli.ts) → [`src/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server.ts) → same Next.js handler chain
- **Port**: Defaults to **20128**, configurable via flags or environment
- **Core LLM logic**: Resides in [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts), invoked by App Router routes
- **MCP tools**: Optional server at [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts)

---

## Frequently Asked Questions

### How do I change the port OmniRoute listens on?

Set the `PORT` environment variable or pass `--port` when using the CLI: `omniroute --port 8080`. The default 20128 is hardcoded in [`src/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server.ts) but overridden by configuration parsing in [`src/cli.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/cli.ts).

### Can I run OmniRoute without Next.js's dev server?

Yes. Import [`src/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server.ts) directly in your own Node.js application. This bypasses `next dev` and gives you full control over the HTTP server lifecycle while retaining all API functionality.

### What file handles the actual LLM routing logic?

[`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts) contains the core implementation. It receives normalized requests from [`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts), selects the appropriate model/provider, and manages streaming responses.

### Is there a separate entry point for MCP tool support?

Yes. When `--mcp` is enabled, [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) initializes. This runs alongside the main server rather than replacing it, enabling simultaneous HTTP API and MCP tool access.