How to Configure OmniRoute as a Reverse Proxy to Serve Under a Subpath Using OMNIROUTEBASEPATH

Set the OMNIROUTEBASEPATH environment variable to automatically prefix all routes, static assets, and API endpoints with your desired subpath, enabling seamless reverse proxy integration without modifying application code.

OmniRoute is built on Next.js 16 (App Router), which natively supports the basePath configuration option for subpath deployments. By leveraging the OMNIROUTEBASEPATH environment variable, you can deploy OmniRoute behind any reverse proxy—such as NGINX, Traefik, or Caddy—under a custom URL prefix. This guide explains the complete configuration flow based on the actual source code in the diegosouzapw/OmniRoute repository.

How OMNIROUTEBASEPATH Configures the Base Path

The subpath configuration is handled in src/server/next.config.ts, where the environment variable is read at build time and injected into the Next.js configuration. When OMNIROUTEBASEPATH is set, both the basePath and assetPrefix properties are updated to ensure consistent routing.

In src/server/next.config.ts (lines 5‑12), the configuration logic reads:

// src/server/next.config.ts
const basePath = process.env.OMNIROUTEBASEPATH?.trim() ?? "";
export default {
  // …other Next.js options…
  ...(basePath && { basePath }),                     // ← adds the sub‑path
  // Ensure asset prefix matches the base path
  assetPrefix: basePath ? `${basePath}/_next` : undefined,
};

Setting assetPrefix to ${basePath}/_next ensures that compiled JavaScript, CSS, and image bundles are served from the correct location when running behind a reverse proxy. This eliminates 404 errors for static assets that would otherwise be requested from the domain root.

Step-by-Step Configuration Guide

1. Set the Environment Variable

You can define OMNIROUTEBASEPATH in a .env file, export it in your shell, or pass it inline when starting the server.

Using a .env file:

# .env (project root)

OMNIROUTEBASEPATH=/omni
OMNIROUTE_PORT=8080

Running inline:

OMNIROUTEBASEPATH=/api/v1 omniroute serve --port 5000

The bin/cli/serve.ts entry point loads these variables via dotenv before launching the Next.js runtime, ensuring the configuration is available immediately during startup.

2. Configure Your Reverse Proxy

Your reverse proxy must forward requests to OmniRoute while preserving the subpath. The proxy_pass directive must include the same subpath defined in OMNIROUTEBASEPATH.

NGINX configuration example:

server {
    listen 80;
    server_name mydomain.com;

    location /omni/ {
        proxy_pass http://127.0.0.1:8080/omni/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

For Traefik or Caddy, configure the equivalent path stripping or prefix preservation rules to match the OMNIROUTEBASEPATH value.

3. Verify the Deployment

After starting OmniRoute, check the server logs for the resolved base URL:

[info] OmniRoute base path: /omni

Test the health endpoint to confirm the subpath is working:

curl http://localhost:8080/omni/api/v1/health

A successful response indicates that API routes under src/app/api/** are correctly prefixed and accessible.

Technical Implementation Details

Bootstrap Process

The bin/cli/serve.ts file serves as the CLI entry point for the omniroute serve command. It initializes environment variables before the Next.js server starts, ensuring that OMNIROUTEBASEPATH is available when next.config.ts is evaluated.

Route Adaptation

All API routes in src/app/api/** are defined without leading slashes. Next.js automatically prepends the configured basePath when building the final URL mapping. This means a file located at src/app/api/v1/chat/completions/route.ts automatically becomes accessible at /<base‑path>/api/v1/chat/completions without requiring manual string concatenation or route rewriting in your application code.

Testing Base Path Resolution

The repository includes unit tests that validate the base path behavior. The file tests/unit/resolve-omniroute-base-url.test.ts confirms that OMNIROUTEBASEPATH correctly overrides the default base URL resolution logic, ensuring consistent behavior across different deployment environments.

Run the test suite to verify your configuration:

npm test -- tests/unit/resolve-omniroute-base-url.test.ts

Summary

• OMNIROUTEBASEPATH is the environment variable that controls subpath deployment in OmniRoute.
• The variable is processed in src/server/next.config.ts to set Next.js basePath and assetPrefix.
• Static assets are automatically remapped to <base‑path>/_next/* to prevent 404 errors behind proxies.
• No code changes are required in API route handlers; Next.js handles prefixing automatically.
• The bin/cli/serve.ts bootstrap ensures environment variables are loaded before the server initializes.

Frequently Asked Questions

What is the exact spelling of the environment variable for subpath configuration?

The environment variable is OMNIROUTEBASEPATH (without underscores between words). It is defined in src/server/next.config.ts and read via process.env.OMNIROUTEBASEPATH.

Does setting OMNIROUTEBASEPATH affect both API routes and frontend assets?

Yes. The configuration sets both the Next.js basePath (affecting API routes and page navigation) and assetPrefix (affecting _next static bundles). This ensures that src/app/api/v1/health/route.ts and all compiled JavaScript are served from the correct subpath.

Can I change the base path without rebuilding the OmniRoute container?

Since src/server/next.config.ts is evaluated at build time in Next.js, changing OMNIROUTEBASEPATH requires a restart of the OmniRoute process, and in some static deployment scenarios, a rebuild. For dynamic containerized environments, set the variable before the next build step or use runtime configuration for truly dynamic values.

How do I handle trailing slashes when configuring NGINX with OmniRoute?

Ensure the proxy_pass URL in your NGINX location block includes the trailing slash and matches OMNIROUTEBASEPATH exactly. For example, if OMNIROUTEBASEPATH=/omni, use proxy_pass http://127.0.0.1:3000/omni/;. Mismatched slashes can result in 404 errors or incorrect route resolution.

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