Where Is the Main Entry Point for the OmniRoute Application?

The main entry point for OmniRoute is the Next.js 15 runtime, launched via npm scripts in package.json, which loads API routes from src/app/. For CLI usage, the chain starts at src/cli.ts and delegates to 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, the relevant scripts are:

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

These invoke the Next.js runtime, which then:

1. Reads 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

When OmniRoute runs as a standalone server—either through the CLI or programmatically—the critical file is 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:

• 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

For command-line usage, the entry point shifts to src/cli.ts. This module parses arguments, loads configuration, and orchestrates startup.

Typical invocation flow:

# Via npx or global install

omniroute --port 3000 --mcp

What happens internally:

1. 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 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 — 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

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

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	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	Processes LLM routing logic
CLI bootstrap	src/cli.ts	Parses args, loads config
Server creation	src/server.ts	Creates HTTP server on port 20128
MCP mode	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 → 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, invoked by App Router routes
• MCP tools: Optional server at 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 but overridden by configuration parsing in src/cli.ts.

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

Yes. Import 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 contains the core implementation. It receives normalized requests from 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 initializes. This runs alongside the main server rather than replacing it, enabling simultaneous HTTP API and MCP tool access.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}