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

> Configure OmniRoute as a reverse proxy serving under a subpath. Set OMNIROUTEBASEPATH env var to prefix routes and assets without code changes. Integrate seamlessly.

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

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/next.config.ts) (lines 5‑12), the configuration logic reads:

```typescript
// 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:

```dotenv

# .env (project root)

OMNIROUTEBASEPATH=/omni
OMNIROUTE_PORT=8080

```

Running inline:

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

```

The [`bin/cli/serve.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:**

```nginx
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:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.