OmniRoute Remote Mode: Complete Setup Guide for Remote Server Management

OmniRoute remote mode enables local CLI control of remote server instances using scoped access tokens, allowing you to manage VPS, Docker, or cloud-hosted deployments without exposing internal credentials.

OmniRoute supports two operational architectures: a local server (the default) and remote mode. When configured for remote mode, the CLI client drives an OmniRoute instance hosted on a different machine—such as a VPS, Docker container, or cloud host—using specialized scoped tokens rather than traditional API-key flows. According to the diegosouzapw/OmniRoute source code, this architecture allows secure management of remote resources while maintaining strict access controls through the Route Guard Tiers system.

What Is OmniRoute Remote Mode?

In the default configuration, OmniRoute runs as a local server on your machine. Remote mode decouples the CLI client from the server, enabling you to execute management commands against a remote instance. This is achieved through scoped CLI access tokens that use a special oma_… format.

Key characteristics of remote mode:

• Scoped authentication: Tokens follow the format oma_<…> and are evaluated before standard API-key validation at the server level.
• Management-level access: These tokens grant permission to invoke administrative actions on the remote instance without exposing the server’s internal credentials.
• Remote-aware commands: Setup and launch commands automatically inject remote endpoints and authentication headers (such as ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN) into local configuration files.

How Scoped Access Tokens Work

The remote mode security model relies on scoped access tokens defined in the OmniRoute source code. When a client presents a token starting with oma_, the server evaluates it through a dedicated authentication branch before falling back to standard API-key validation.

Core implementation files:

• src/server/authz/accessTokenAuth.ts: Handles the validation and parsing of scoped tokens, ensuring they are processed before the normal API-key branch.
• src/lib/accessTokens/scopes.ts: Defines the available token scopes and permissions, determining which management actions a remote client can perform.

This design ensures that remote connections receive only the specific permissions encoded in the token, adhering to the principle of least privilege.

Setting Up OmniRoute Remote Mode

Configuring remote mode requires generating a scoped token, storing a remote context, and activating it for CLI use.

Step 1: Generate a Scoped Token

Use the omniroute login command to create a one-time credential blob that encodes the required scopes. For example:

omniroute login antigravity \
  --remote http://my-remote-host:20128 \
  --api-key oma_live_XXXXXXXXXXXXXXXX

This command authenticates you to the remote OmniRoute instance and returns a scoped token for subsequent operations.

Step 2: Store the Remote Context

Persist the remote configuration for reuse across sessions using omniroute connect:

omniroute connect my-remote \
  --remote http://my-remote-host:20128 \
  --api-key oma_live_XXXXXXXXXXXXXXXX

Step 3: Activate the Remote Context

Switch to your stored remote context to make it the active target for all subsequent commands:

omniroute use my-remote

Once activated, all omniroute setup-* and omniroute launch commands automatically target this remote server without requiring additional flags.

Configuring AI Tools for Remote Access

Remote-aware CLI commands fetch the remote provider catalog and write local configuration files that point to the remote OmniRoute endpoint.

Provider Setup Commands

Commands such as omniroute setup-claude, omniroute setup-codex, and omniroute setup-opencode accept --remote <url> and --api-key <key> flags. When a remote context is active, these flags are optional because the CLI uses the stored token and URL automatically.

omniroute setup-claude \
  --model claude-3-sonnet-20240229 \
  --profile my-claude

This generates a configuration file at ~/.claude/profiles/<profile>/settings.json containing the remote OmniRoute URL and scoped token.

Launch Commands

Launch commands respect the active remote context by injecting the appropriate environment variables:

• ANTHROPIC_BASE_URL (or equivalent for other providers)
• ANTHROPIC_AUTH_TOKEN (or equivalent)

omniroute launch --profile my-claude

The local Claude client now communicates directly with the remote OmniRoute instance rather than a local server.

OAuth and Reverse Tunnel Hints

When a remote client initiates an OAuth flow (for example, with Codex or Claude), the server detects the remote connection and returns a reverse-tunnel hint instead of attempting a localhost callback that would be unreachable from the user’s browser.

The hint includes:

• remoteHost: The target remote host identifier
• tunnelCommand: Instructions for establishing the reverse tunnel
• message: Human-readable guidance for the user

This logic is implemented in src/app/api/oauth/[provider]/[action]/remoteOAuthHint.ts, preventing authentication failures in remote mode deployments.

Security Model and Route Guard Tiers

Remote mode is governed by the Route Guard Tiers system, which classifies endpoints by their accessibility requirements:

• LOCAL_ONLY endpoints: Accessible without scoped tokens, restricted to localhost connections
• Management-scope endpoints: Including /api/mcp/*, reachable from remote hosts only when the caller presents a valid oma_… token

The policy enforcement logic resides in src/server/authz/policies/management.ts, ensuring that remote clients cannot access sensitive administrative functions without proper authorization. This tiered approach allows the server to safely expose management APIs to remote CLI clients while maintaining strict boundaries around internal operations.

Summary

• OmniRoute remote mode allows local CLI control of server instances hosted on VPS, Docker containers, or cloud platforms.
• Authentication uses scoped access tokens (oma_… format) validated in src/server/authz/accessTokenAuth.ts and defined in src/lib/accessTokens/scopes.ts.
• Configure remote access using omniroute connect to store contexts and omniroute use to activate them.
• Setup commands (omniroute setup-claude, etc.) automatically configure local AI tools to communicate with remote endpoints.
• The Route Guard Tiers system in src/server/authz/policies/management.ts ensures remote connections adhere to strict security policies.
• OAuth flows in remote mode receive reverse-tunnel hints from src/app/api/oauth/[provider]/[action]/remoteOAuthHint.ts to handle browser redirects correctly.

Frequently Asked Questions

What is the difference between local and remote mode in OmniRoute?

Local mode runs the OmniRoute server on your machine alongside the CLI, using standard API-key authentication. Remote mode separates the client and server, allowing the CLI to control an OmniRoute instance on a different machine using scoped tokens (oma_…) instead of exposing the server’s internal credentials to the client.

How do I generate a scoped access token for remote mode?

Run omniroute login <provider> with the --remote and --api-key flags, or use omniroute connect to store a permanent context. The server generates a token with the oma_ prefix containing encoded scopes defined in src/lib/accessTokens/scopes.ts, which the CLI stores in your local configuration for subsequent authenticated requests.

Is remote mode secure for production environments?

Yes, provided you follow the Route Guard Tiers security model implemented in src/server/authz/policies/management.ts. Remote mode requires valid scoped tokens for all management-scope endpoints, and the src/server/authz/accessTokenAuth.ts layer validates these tokens before processing requests. Sensitive LOCAL_ONLY endpoints remain inaccessible to remote connections, ensuring internal operations stay protected.

Can I use remote mode with any AI provider supported by OmniRoute?

Yes. Remote mode works with all supported providers including Claude, Codex, and OpenCode. The omniroute setup-* commands fetch the remote provider catalog and configure local tool settings to use the remote endpoint, while omniroute launch injects the appropriate ANTHROPIC_BASE_URL (or equivalent) and authentication headers for each provider.

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