How OmniRoute Remote Mode with Scoped Tokens Works for VPS Installations

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:

# 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 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, 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 inspects the Authorization header (line 6). Tokens must use the Bearer oma_ prefix:

// 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 evaluates the token's authorization (line 276). This policy runs before the standard API-key authentication branch:

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

# 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

# === 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	Hierarchy and permission constants
Token validation	src/server/authz/accessTokenAuth.ts	Bearer extraction and JWT verification
Authorization policy	src/server/authz/policies/management.ts	Scope-based access control enforcement
Usage documentation	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 restricts access to administrative endpoints only.
• accessTokenAuth.ts validates tokens; 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 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.

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