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

> Learn how to set up remote mode with OmniRoute. Control your server instance from your local CLI with tokens and context management. Complete guide.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-15

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/_shared/auth.ts), validates scoped tokens passed via the `Authorization` header, while [`src/lib/auth/token.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```bash
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:

```bash
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:

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

```

Activate the context for the current session:

```bash
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):**

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

```

**Using an active context:**

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/CLI-INTEGRATIONS.md).

## Switching Between Local and Remote Mode

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

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/auth/token.ts)** (token logic), and **[`src/app/api/v1/_shared/auth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/auth/token.ts). For production, configure TLS termination and reverse proxies (documented in [`docs/guides/REMOTE-MODE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/REMOTE-MODE.md)) to encrypt traffic between your local CLI and the remote OmniRoute server.