How to Configure OmniRoute for Remote Mode with Scoped Tokens

Run OmniRoute in remote mode by creating a CLI profile that points to a remote server and authenticates each request using short-lived scoped tokens injected into the Authorization: Bearer header.

OmniRoute supports remote mode as of v3.8.50, allowing you to run the local CLI against a remote OmniRoute server without maintaining a user session on that instance. This guide shows you how to configure remote mode using scoped access tokens that limit permissions to specific providers and models.

What Is Remote Mode in OmniRoute?

Remote mode rearchitects the standard OmniRoute workflow:

• Local CLI handles command parsing, profile management, and token injection
• Remote OmniRoute server validates tokens and executes the request against upstream providers
• Scoped tokens provide temporary, least-privilege access without full authentication

This approach is ideal for distributed teams, CI/CD pipelines, or scenarios where you want to centralize OmniRoute infrastructure without giving every user shell access to the server.

Prerequisites

Before configuring remote mode, ensure you have:

1. OmniRoute CLI v3.8.50 or later (verify with omniroute --version)
2. A running remote OmniRoute instance with HTTPS enabled
3. Access to a token source (OAuth flow, static API key, or external secret manager)

The remote mode feature was introduced in v3.8.50; see the changelog entry at CHANGELOG.md lines 3901-3902 for the original announcement.

Step 1: Create a Remote Profile

Use the omniroute configure codex command with the --remote-url flag to create a profile that targets a remote server. The CLI entry point at bin/omniroute.mjs parses these flags and stores the configuration for subsequent invocations.

omniroute configure codex \
  --remote-url https://my-remote-omniroute.example.com \
  --token-source env

Parameter breakdown:

• --remote-url — The HTTPS endpoint of your remote OmniRoute instance
• --token-source env — Directs the CLI to read the token from the OMNIRoute_TOKEN environment variable (alternatively: --token-source file:/path/to/token.txt)

As documented in README.md lines 706-707, this creates a local Codex profile that transparently routes all requests to the specified remote server.

Step 2: Provide a Scoped Token

Scoped tokens are short-lived credentials that grant limited permissions. Before each request, the CLI obtains the token from your configured source and injects it into the HTTP headers.

# Export a scoped token (JWT or any format your remote server accepts)

export OMNIRoute_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

The token's scope determines which providers and models you can access. A properly scoped token might encode claims like:

{
  "sub": "service-account-123",
  "scope": "provider:openai model:gpt-4",
  "exp": 1717171717
}

Your remote OmniRoute server's token validation logic — located in the core authentication libraries referenced in the changelog — verifies these claims before forwarding requests to providers.

Step 3: Execute Commands Against the Remote Server

With the profile configured and token exported, use OmniRoute normally:

# Start an interactive chat session through the remote instance

omniroute chat "Explain the benefits of remote mode" --profile codex

# Or run a single completion

omniroute complete "Write a Python function to parse JSON" --profile codex

The CLI automatically attaches Authorization: Bearer <token> to every HTTPS request. If the token is invalid, expired, or lacks sufficient scope, the remote server returns a 401 Unauthorized error with a clear message.

Token Source Options

OmniRoute supports multiple token acquisition strategies:

--token-source value	Behavior	Best for
env	Reads from OMNIRoute_TOKEN environment variable	Development, CI pipelines
file:<path>	Reads token from a file on disk	Kubernetes secrets, tmpfs mounts
exec:<command>	Executes a command that outputs the token	External credential providers, HashiCorp Vault

The CLI re-reads the token before each request, enabling seamless token rotation without restarting the process.

Validation Flow: How the Remote Server Handles Tokens

When your CLI sends a request, the remote OmniRoute instance executes this validation pipeline (as implemented in the token validator referenced in the changelog):

1. Extract the Authorization: Bearer <token> header
2. Validate token signature and expiration using built-in token-validation utilities
3. Check scope against the requested provider and model
4. Forward to the provider execution pipeline (executors → handlers → streaming engine) if authorized
5. Return 401 with descriptive error if any check fails

This architecture keeps sensitive provider credentials on the remote server while letting clients operate with minimal, revocable permissions.

Securing Your Configuration

Follow these practices when configuring OmniRoute for remote mode with scoped tokens:

• Short expiration: Issue tokens with brief lifetimes (minutes, not hours) and rotate frequently
• Minimal scope: Restrict each token to a single provider/model combination
• TLS only: Always use https:// URLs; the CLI rejects plaintext http:// remote URLs
• Audit logging: Enable request logging on your remote server to track token usage

For comprehensive security guidance and advanced token scope configurations, refer to docs/guides/REMOTE-MODE.md in the repository.

Troubleshooting Common Issues

"401 Unauthorized" on every request

Verify your token is valid and unexpired. Check the remote server's logs for specific validation failures — the token validator provides detailed error contexts.

"Invalid remote URL" error

Ensure your --remote-url uses https:// and includes no trailing path. The CLI expects the base URL only; it appends /v1/... endpoints automatically.

Token file permissions

When using --token-source file, ensure the file is readable by the OmniRoute process but not world-readable (chmod 600 recommended).

Summary

• Remote mode lets a local OmniRoute CLI drive a remote server without maintaining a session on that instance
• Scoped tokens provide temporary, limited permissions via Authorization: Bearer headers
• Create remote profiles with omniroute configure codex --remote-url <URL> --token-source <source>
• Token sources include environment variables, files, and executable commands for flexible credential management
• The feature was introduced in v3.8.50; full documentation lives in docs/guides/REMOTE-MODE.md

Frequently Asked Questions

How do I rotate tokens without restarting the CLI?

OmniRoute re-reads the token from its configured source before every request. If using --token-source file, simply overwrite the file contents with a new token. For --token-source env, export the updated variable in your shell session before the next invocation.

What token formats does OmniRoute accept?

The remote server's token validator accepts any format you configure it to validate. Common choices include JWTs signed with RS256 or HS256, opaque bearer tokens from OAuth 2.0 providers, or API keys from enterprise identity systems. The scope claims determine authorization, not the token structure itself.

Can I use remote mode with multiple remote servers simultaneously?

Yes. Create separate profiles with distinct names using omniroute configure <profile-name> --remote-url <URL> for each server. Specify the desired profile with --profile <name> on every command. Each profile maintains its own token source configuration.

Is remote mode slower than local mode?

Each request incurs additional HTTPS round-trip latency to the remote server, typically 20-100ms depending on network conditions. The token validation overhead is negligible (<1ms) due to efficient caching in the remote server's validator. For latency-sensitive applications, consider co-locating the remote server with your CLI environment.

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