How to Set Up Remote Mode for Controlling OmniRoute from a Local CLI

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, 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:

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, running omniroute context use <name> updates the default target for all subsequent invocations.

Switch to the remote context with:

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 <token> header. The remote server validates the token through its normal authorization pipeline and processes the request exactly as if it were local. For example:

# 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 to enforce zero-trust safety: only the scoped token stored in the context is used.

The runtime logic in 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 — 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 — Compatibility layer ensuring older CLI commands respect the new --remote and --api-key flags.
• src/shared/services/cliRuntimeHealthcheckPath.ts — Provides health-check endpoints for remote CLI monitoring.
• src/shared/services/cliRuntimeGrokBuild.ts — Handles remote-aware Grok-build support for tools like Claude Code and Codex.
• 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 routes all traffic to the remote host.
• Run standard commands like omniroute chat or omniroute embed; the CLI automatically adds the Authorization: Bearer <token> 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 <url> and --api-key <key> directly on a per-command basis. The compatibility layer in 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 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.

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