# How to Set Up Remote Mode for Controlling OmniRoute from a Local CLI > Learn to set up remote mode for OmniRoute controlling from your local CLI. Configure contexts, activate remote access, and route commands instantly via authenticated HTTP requests. - Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute) - Tags: how-to-guide - Published: 2026-07-27 --- **TLDR:** Configure a named remote context with `omniroute contexts add`, activate it with `omniroute context use`, and every subsequent CLI command is automatically routed to the remote OmniRoute server via authenticated HTTP requests. OmniRoute supports a remote mode that turns a local CLI into a client for a server running anywhere—from a local workstation to a VPS or Docker container. By storing remote endpoints and scoped tokens in `~/.omniroute/contexts.json`, the CLI can execute commands like `omniroute chat` and `omniroute embed` against a remote host without installing the full UI there. This guide explains how to set up remote mode for controlling OmniRoute from a local CLI using the exact workflow implemented in the `diegosouzapw/OmniRoute` source code. ## Create a Remote Context The first step is to define a named context that stores the remote base URL and a scoped API key. According to [`src/shared/services/cliRuntime.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/services/cliRuntime.ts), the CLI persists these entries to `~/.omniroute/contexts.json` and loads them before every request. Use the `omniroute contexts add` command to create a context. The example below creates a context named `my-vps` and generates a scoped token for it: ```bash omniroute contexts add my-vps \ --remote https://omni.my-vps.example.com \ --api-key $(omniroute token generate --scope manage) ``` After running this command, the context is permanently stored and available across sessions. ## Select the Active Context Once a context exists, you must tell the CLI to use it. As implemented in [`src/shared/services/cliRuntime.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/services/cliRuntime.ts), running `omniroute context use ` updates the default target for all subsequent invocations. Switch to the remote context with: ```bash omniroute context use my-vps ``` Alternatively, you can override the active context on a per-command basis with the `--remote` and `--api-key` flags without changing the stored default. This ephemeral approach is useful in CI pipelines or when switching between environments temporarily. ## Run Commands Against the Remote Server After selecting a remote context, standard OmniRoute CLI commands are translated into HTTP requests to the remote endpoint at `/v1/...`. The entry point in `bin/cli/program.mjs` wires the `contexts` sub-command and propagates the selected context to the runtime. The local CLI automatically injects an `Authorization: Bearer ` header. The remote server validates the token through its normal authorization pipeline and processes the request exactly as if it were local. For example: ```bash # Chat completion against the remote server omniroute chat "Explain quantum tunneling in plain English" # Generate embeddings using the remote provider catalog omniroute embed "Fast, reliable embeddings" --model openai/gpt-4o-mini ``` Because the remote instance maintains the provider catalog and credentials, you do not need local copies of model configurations or environment secrets. ## Remote Mode Security and Scoped Tokens When a remote context is active, the OmniRoute CLI ignores ambient environment variables such as `OMNIROUTE_API_KEY`. This behavior was hardened in pull request [#4364](https://github.com/diegosouzapw/OmniRoute/pull/4364) to enforce zero-trust safety: only the scoped token stored in the context is used. The runtime logic in [`src/shared/services/cliRuntime.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/services/cliRuntime.ts) reads the selected context and injects both the remote base URL and the scoped token into every outgoing HTTP request. This separation of concerns keeps sensitive provider credentials on the dedicated host while your local workstation drives the server. ## Key Source Files for Remote Mode Remote mode is implemented across several files in the `diegosouzapw/OmniRoute` repository: - **[`src/shared/services/cliRuntime.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/services/cliRuntime.ts)** — Core runtime that reads the selected context and injects the remote base URL and token into every HTTP request. - **`bin/cli/program.mjs`** — Entry point for the `omniroute` executable; wires the `contexts` sub-command and propagates the active context to the runtime. - **[`src/shared/utils/cliCompat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/cliCompat.ts)** — Compatibility layer ensuring older CLI commands respect the new `--remote` and `--api-key` flags. - **[`src/shared/services/cliRuntimeHealthcheckPath.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/services/cliRuntimeHealthcheckPath.ts)** — Provides health-check endpoints for remote CLI monitoring. - **[`src/shared/services/cliRuntimeGrokBuild.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/services/cliRuntimeGrokBuild.ts)** — Handles remote-aware Grok-build support for tools like Claude Code and Codex. - **[`docs/guides/REMOTE-MODE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/REMOTE-MODE.md)** — User-facing documentation covering context-management commands and best-practice tips. ## Summary Setting up remote mode for controlling OmniRoute from a local CLI requires just three steps: - Create a named remote context with `omniroute contexts add` to store the base URL and a scoped API key in `~/.omniroute/contexts.json`. - Activate the context with `omniroute context use` so that [`src/shared/services/cliRuntime.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/services/cliRuntime.ts) routes all traffic to the remote host. - Run standard commands like `omniroute chat` or `omniroute embed`; the CLI automatically adds the `Authorization: Bearer ` header and targets the `/v1/...` endpoints. ## Frequently Asked Questions ### Can I override the remote context for a single command? Yes. Instead of switching the default context with `omniroute context use`, you can pass `--remote ` and `--api-key ` directly on a per-command basis. The compatibility layer in [`src/shared/utils/cliCompat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/cliCompat.ts) ensures these flags are respected by older commands, making them ideal for ephemeral CI jobs or ad-hoc debugging. ### Why does the CLI ignore my OMNIROUTE_API_KEY in remote mode? OmniRoute enforces zero-trust safety by requiring scoped tokens for remote connections. When a remote context is active, the runtime in [`src/shared/services/cliRuntime.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/services/cliRuntime.ts) ignores ambient variables like `OMNIROUTE_API_KEY` and uses only the scoped token stored in `~/.omniroute/contexts.json` or passed via the `--api-key` flag. This prevents accidental credential misuse and was hardened in PR #4364. ### Which commands can I run against a remote OmniRoute server? You can run all standard CLI tools remotely, including `omniroute chat`, `omniroute embed`, and `omniroute launch`. The runtime routes requests to the remote host’s `/v1/...` endpoints automatically, and the remote server processes them through its normal authorization pipeline exactly as if they were local. ### Do I need the OmniRoute UI installed locally to use remote mode? No. Remote mode is designed so that a lightweight local CLI can control a remote OmniRoute server running on a workstation, VPS, or Docker container. You do not need the full UI on your local machine; you only need a valid context and the CLI binary.