# How OmniRoute Remote Mode with Scoped Tokens Works for VPS Installations

> Learn how OmniRoute remote mode uses scoped tokens for secure VPS installations, allowing local CLI control without API keys. Get enhanced security and flexibility.

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

---

**OmniRoute remote mode lets you run the server on a VPS and control it from a local CLI using time-limited, scope-restricted tokens instead of API keys.**

OmniRoute's **remote mode** is designed for teams who want to host the routing layer on a dedicated server while retaining the convenience of local CLI administration. Rather than exposing API keys across network boundaries, the system uses **scoped CLI access tokens**—JWT-style credentials prefixed with `oma_`—that grant only the permissions needed for management operations. This architecture is implemented across `src/lib/accessTokens/`, `src/server/authz/`, and the CLI configuration layer in diegosouzapw/OmniRoute.

## Generating a Scoped Token for Remote Access

Remote mode begins on the VPS itself. Administrators generate a token using the built-in CLI command, which encodes identity, permissions, and expiry into a single string.

### Token Structure and Generation Command

Run `omniroute token generate` (or `omniroute configure` with remote-mode flags) on the server:

```bash

# Generate a management-scoped token valid for 30 days

omniroute token generate --scope=management --expires=30d > ~/.omniroute/remote.token

```

The resulting JWT contains:

- `sub` — a subject identifier for the CLI instance
- `scope` — the permission boundary (see hierarchy below)
- `exp` — expiration timestamp (default ≈30 days)

Store this token securely; it becomes the sole credential for remote administrative access.

## Scope Hierarchy and Permission Boundaries

Scopes are defined in **[`src/lib/accessTokens/scopes.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/accessTokens/scopes.ts)** and follow a three-level hierarchy:

```

global → provider → model

```

This design allows fine-grained control over what remote callers can do. For VPS installations, the **`management`** scope is the standard choice. According to the source code at line 2 of [`src/lib/accessTokens/scopes.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/accessTokens/scopes.ts), this scope grants access to:

- Health check endpoints (`/api/v1/health`)
- Provider and model synchronization (`/api/v1/providers/:id/models`)
- Configuration management (`/api/v1/config`)

Importantly, `management` explicitly **excludes** chat and completion routes—protecting downstream LLM provider credentials even if the token is compromised.

## Authentication Flow: How Remote Tokens Are Validated

### Step 1: Access-Token Middleware

When a request arrives, **[`src/server/authz/accessTokenAuth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/accessTokenAuth.ts)** inspects the `Authorization` header (line 6). Tokens must use the `Bearer oma_` prefix:

```ts
// Simplified extraction from accessTokenAuth.ts
const auth = req.headers.authorization;
if (!auth?.startsWith('Bearer oma_')) return next();

const token = auth.slice('Bearer '.length);
const payload = await verifyToken(token);  // signature + expiry validation
req.auth = { scope: payload.scope, sub: payload.sub };

```

If validation succeeds, the scope and subject attach to the request context for downstream enforcement.

### Step 2: Management Policy Evaluation

Before any route handler executes, **[`src/server/authz/policies/management.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/policies/management.ts)** evaluates the token's authorization (line 276). This policy runs **before** the standard API-key authentication branch:

```ts
// Simplified policy logic from management.ts
export function managementPolicy(req, res, next) {
  if (req.auth?.scope === 'management') {
    // Permit only whitelisted management routes
    return next();
  }
  // Fall through to API-key authentication for other requests
  return next();
}

```

This ordering ensures that remote-mode tokens take precedence and cannot be overridden by API-key logic.

## Configuring the Local CLI for VPS Control

Pass the token to your local OmniRoute CLI via environment variable or flag:

```bash

# From local workstation, target the VPS

export OMNIROUTE_REMOTE_TOKEN=$(cat ~/.omniroute/remote.token)
export OMNIROUTE_REMOTE_URL=https://my-vps.example.com

# Execute management commands remotely

omniroute providers sync --provider codex
omniroute health check
omniroute config set --key log.level --value debug

```

The CLI detects `OMNIROUTE_REMOTE_URL` and routes all traffic to the specified endpoint, attaching the token from `OMNIROUTE_REMOTE_TOKEN` to each request.

## Security Benefits of Scoped Tokens

**Compromise containment** — A stolen `management` token cannot generate completions or access chat APIs, limiting attacker utility to read-only or administrative operations.

**Time bounding** — Default 30-day expiry forces rotation without manual policy enforcement.

**Audit granularity** — The `sub` claim identifies specific CLI installations, enabling per-workstation access logging.

## Complete Remote Mode Workflow Example

```bash

# === ON THE VPS ===

# 1. Generate and store token

omniroute token generate --scope=management --expires=30d > ~/.omniroute/remote.token

# 2. Start server in remote mode (token required for CLI binding)

OMNIROUTE_REMOTE_TOKEN=$(cat ~/.omniroute/remote.token) \
  omniroute start --remote-mode --port 443

# === ON LOCAL WORKSTATION ===

# 3. Copy token securely (scp, password manager, etc.)

scp vps:~/.omniroute/remote.token ~/.omniroute/

# 4. Execute remote commands

OMNIROUTE_REMOTE_TOKEN=$(cat ~/.omniroute/remote.token) \
OMNIROUTE_REMOTE_URL=https://my-vps.example.com \
  omniroute providers list

```

## Key Implementation Files

| Purpose | File Path | Relevance |
|---------|-----------|-----------|
| Scope definitions | [`src/lib/accessTokens/scopes.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/accessTokens/scopes.ts) | Hierarchy and permission constants |
| Token validation | [`src/server/authz/accessTokenAuth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/accessTokenAuth.ts) | Bearer extraction and JWT verification |
| Authorization policy | [`src/server/authz/policies/management.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/policies/management.ts) | Scope-based access control enforcement |
| Usage documentation | [`docs/guides/REMOTE-MODE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/REMOTE-MODE.md) | CLI flags, examples, troubleshooting |

## Summary

- **Remote mode** replaces API-key authentication with **scoped JWT tokens** for VPS installations.
- Tokens are generated via `omniroute token generate` and prefixed with `oma_`.
- The **`management`** scope in [`src/lib/accessTokens/scopes.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/accessTokens/scopes.ts) restricts access to administrative endpoints only.
- **[`accessTokenAuth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/accessTokenAuth.ts)** validates tokens; **[`management.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/management.ts)** enforces policy before API-key checks.
- Local CLI configuration uses `OMNIROUTE_REMOTE_TOKEN` and `OMNIROUTE_REMOTE_URL` environment variables.

## Frequently Asked Questions

### How do I rotate a remote-mode token before it expires?

Generate a new token on the VPS with `omniroute token generate`, update the environment variable on your local workstation, and delete the old token from `~/.omniroute/`. The server accepts multiple valid tokens simultaneously, so rotation happens without downtime.

### Can I create a read-only remote token?

Yes—define a custom scope in [`src/lib/accessTokens/scopes.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/accessTokens/scopes.ts) that omits write permissions, or use the built-in `global:read` scope if available in your OmniRoute version. The management policy will respect whatever scope you encode in the JWT.

### What happens if I start the server without `--remote-mode`?

The server ignores `oma_` tokens entirely and falls back to standard API-key authentication. Remote CLI commands will fail with 401 Unauthorized unless you also supply a valid API key with sufficient permissions.

### Does remote mode work with HTTPS and custom ports?

Absolutely. Set `OMNIROUTE_REMOTE_URL` to any valid origin including port and protocol, such as `https://vps.internal:8443`. The CLI validates the server's TLS certificate normally; use standard environment variables (`NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`) if you operate an internal CA.