How to Run OmniRoute from the Command Line: Complete CLI Setup

Run OmniRoute from the command line by executing npx omniroute serve after installing dependencies, which launches the HTTP server on port 20128 via the CLI entry point at bin/omniroute.mjs.

OmniRoute is a self‑hosted AI proxy and router that exposes a dedicated command‑line interface for server management. According to the diegosouzapw/OmniRoute source code, the CLI is registered in package.json and dispatches commands through a Node.js executable. This guide covers installation, configuration, and execution of the omniroute binary.

Installation and Prerequisites

Before invoking the CLI, you must install Node.js dependencies and prepare the environment configuration.

Install Dependencies

Clone the repository and install packages using the lockfile to ensure reproducible builds. This step prepares the bin/omniroute.mjs script and all runtime libraries required by the server.

git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute
npm ci

Configure Environment Variables

Copy the example environment file to .env and set required secrets. The CLI reads variables such as PORT, JWT_SECRET, and API_KEY_SECRET at startup to initialize the router.

cp .env.example .env

# Edit .env to configure JWT_SECRET and API_KEY_SECRET

Running the OmniRoute CLI

The package.json file maps the omniroute command to bin/omniroute.mjs, enabling both local and global execution.

Local Execution with npx

Run the CLI without a global installation by using npx, which resolves the binary from the local node_modules directory.

npx omniroute serve

Global Installation

Install the package globally to invoke the omniroute command directly from any shell session. This registers the entry point from bin/omniroute.mjs in your system’s executable path.

npm install -g .
omniroute serve

Custom Port Configuration

Override the default port by exporting the PORT environment variable before starting the server. The initialization logic in bin/omniroute.mjs consumes this value when binding the HTTP listener.

export PORT=8080
npx omniroute serve

CLI Subcommands and Architecture

The bin/omniroute.mjs script parses arguments and dispatches to subcommand handlers. While serve starts the production server, additional administrative tasks—such as reset and backup—are available for database maintenance.

Once the CLI initializes, incoming requests are handled by Next.js API routes located in src/app/api/v1/ and core logic in open-sse/handlers/ that processes chat completions and embeddings.

Summary

• Install dependencies with npm ci to prepare the runtime environment.
• Execute the CLI using npx omniroute serve or the globally installed omniroute command.
• Configure secrets in .env (copied from .env.example) including PORT, JWT_SECRET, and API_KEY_SECRET.
• Default port is 20128, overridable via the PORT environment variable.
• Entry point is bin/omniroute.mjs, registered in package.json for npm binary resolution.
• Request handling is implemented in src/app/api/v1/ and open-sse/handlers/ as implemented in diegosouzapw/OmniRoute.

Frequently Asked Questions

What is the default port when I run OmniRoute from the command line?

The default port is 20128. When you execute npx omniroute serve without setting the PORT environment variable, the server binds to this port as defined in the source configuration.

How do I change the port when running OmniRoute CLI?

Set the PORT environment variable before invoking the command. For example, run export PORT=8080 followed by npx omniroute serve to bind the server to port 8080 instead of the default.

Where is the OmniRoute CLI entry point located in the source code?

The CLI entry point is bin/omniroute.mjs. This file contains the argument parsing logic and is registered in package.json under the bin field, enabling the omniroute command through npm.

Can I run OmniRoute CLI without installing dependencies globally?

Yes. After running npm ci to install local dependencies, you can execute npx omniroute serve to run the CLI without a global installation. The npx utility resolves the binary path automatically from the local node_modules.

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