# OmniRoute Remote Mode: Complete Setup Guide for Remote Server Management > Master OmniRoute remote mode for secure server management. This guide details setup for CLI control of VPS, Docker, and cloud deployments using scoped tokens. Protect your credentials. - Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute) - Tags: how-to-guide - Published: 2026-08-24 --- **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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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: ```bash 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`: ```bash 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: ```bash 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 ` and `--api-key ` flags. When a remote context is active, these flags are optional because the CLI uses the stored token and URL automatically. ```bash omniroute setup-claude \ --model claude-3-sonnet-20240229 \ --profile my-claude ``` This generates a configuration file at `~/.claude/profiles//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) ```bash 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/accessTokenAuth.ts) and defined in [`src/lib/accessTokens/scopes.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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 ` 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/policies/management.ts). Remote mode requires valid scoped tokens for all management-scope endpoints, and the [`src/server/authz/accessTokenAuth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.