How to Set Up Remote Mode with OmniRoute: A Complete Guide

Remote mode in OmniRoute enables you to control a server instance running on a VPS or cloud host from your local CLI using scoped tokens and context management.

OmniRoute is an open-source LLM routing platform that supports remote operation, allowing developers to centralize model provider management on a dedicated server while interacting with it from any local machine. Setting up remote mode involves starting the server on your remote host, generating secure access credentials, and configuring your local CLI to target that instance.

Architecture of Remote Mode

Remote mode operates through a client-server architecture where the OmniRoute server listens on a configurable port (default 20128) and your local CLI acts as the client. According to the source code in bin/cli/program.mjs, the CLI parses --remote and --api-key flags to route API calls to the specified host instead of localhost.

The authentication layer, implemented in src/app/api/v1/_shared/auth.ts, validates scoped tokens passed via the Authorization header, while src/lib/auth/token.ts handles token generation and scope verification on the client side.

Installing and Starting the Remote Server

First, install OmniRoute on your target machine and start the server process.

Connect to your remote host via SSH and install the package globally:

npm install -g omniroute
omniroute start &

By default, the server exposes an HTTP endpoint on port 20128. You can verify the server is running by checking that the process is listening on the expected interface. For production deployments, consult the docs/guides/REMOTE-MODE.md file for TLS termination and NGINX reverse proxy configurations.

Generating Scoped Access Tokens

Remote connections require a scoped token to authenticate requests. OmniRoute supports OAuth-based flows and manual token generation.

Using Google OAuth (Recommended):

Run the following command on your local machine to trigger the authentication flow:

omniroute login antigravity

This stores the credential in ~/.omniroute/tokens.json and prints a token string beginning with omniroute-cred-v1..

Creating a Limited-Scope Token:

For automation or specific use cases, generate a token with restricted permissions:

omniroute token create --scopes remote --expires-in 30d

This creates a token valid only for remote operations that expires after 30 days.

Configuring Remote Contexts

While you can pass --remote and --api-key flags to every command, OmniRoute provides context management to persist these settings.

Add a named context for your remote server:

omniroute contexts add my-vps http://<remote-host>:20128 <token>

Activate the context for the current session:

omniroute contexts use my-vps

Once active, commands like omniroute setup-claude or omniroute launch automatically target the remote instance without requiring explicit flags. As implemented in the CLI, context data is retrieved from local configuration files referenced in bin/cli/program.mjs.

Executing Commands Against the Remote Instance

With the remote server running and authentication configured, you can now execute setup and launch commands targeting the remote host.

Explicit flag usage (no saved context):

omniroute setup-claude \
  --remote http://203.0.113.42:20128 \
  --api-key omniroute-cred-v1.abcdef

Using an active context:

omniroute contexts use my-vps
omniroute launch

The launch command starts Claude Code (or other configured clients) with environment variables ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN pointing to your remote OmniRoute catalog, as detailed in docs/guides/CLI-INTEGRATIONS.md.

Switching Between Local and Remote Mode

To return to local operation, clear the active remote context:

omniroute contexts clear

Alternatively, simply omit the --remote flag when running commands, and the CLI will default to http://localhost:20128.

Summary

• Remote mode allows centralized OmniRoute management on a VPS or cloud server while controlling it from any local machine via the CLI.
• The server listens on port 20128 by default, with authentication handled through scoped tokens stored in ~/.omniroute/tokens.json.
• Use omniroute contexts add and omniroute contexts use to save remote connection details and avoid repetitive flag passing.
• Core implementation resides in bin/cli/program.mjs (flag parsing), src/lib/auth/token.ts (token logic), and src/app/api/v1/_shared/auth.ts (request validation).
• Switch back to local mode anytime using omniroute contexts clear.

Frequently Asked Questions

What port does OmniRoute use for remote mode?

OmniRoute defaults to port 20128 for remote connections. You can specify a custom port when starting the server or when configuring your remote context if your infrastructure requires a different listening port.

How do I create a scoped token for remote access?

Use the command omniroute token create --scopes remote to generate a token limited to remote operations. For interactive use, omniroute login antigravity handles OAuth and stores the credential automatically. Both methods create tokens validated by the middleware in src/app/api/v1/_shared/auth.ts.

Can I switch between local and remote mode easily?

Yes. Run omniroute contexts use <name> to activate a remote context, and omniroute contexts clear to revert to local mode. The CLI checks for an active context in bin/cli/program.mjs before defaulting to localhost, making environment switching seamless.

Is remote mode secure for production use?

Remote mode supports scoped tokens with expiration dates and specific permission sets, implemented in src/lib/auth/token.ts. For production, configure TLS termination and reverse proxies (documented in docs/guides/REMOTE-MODE.md) to encrypt traffic between your local CLI and the remote OmniRoute server.

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