pjandro/OmniRoute
1
0
Fork 0
mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-08-19 05:32:19 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs(cli): fix drifts found in the post-relay documentation audit

Browse Source 
- ENVIRONMENT.md: CLI_ALLOW_CONFIG_WRITES default is true (matches cliRuntime),
  CLI_QODER_BIN default is qodercli (also in .env.example), CLI_GEMINI_BIN is
  server-side detection only (omniroute run resolves from PATH)
- CLI-TOOLS.md: catalog counts 26 code / 8 agents (adds the missing zcode row),
  setup targets without auto-discovery list Qwen (not Gemini; Gemini is
  launch-only), hostSetupCommand only for the six tools with a host recipe,
  global env block uses GOOGLE_GEMINI_BASE_URL at the root, mention
  omniroute run as the generic launcher
- CLI-INTEGRATIONS.md: manifest aliases, per-target --model wiring (openai/ and
  omniroute/ prefixes, qwen hard-requires --model), run exit-code contract,
  gemini child-env scrub notes
- CODEX-CLI-CONFIGURATION.md: document omniroute configure codex / run codex
- SETUP_GUIDE.md + QUICK-START.md: surface the generic omniroute run launcher
- ENVIRONMENT.md: disambiguate OMNIROUTE_SMOKE_API_KEY (canary) from the
  OMNIROUTE_SMOKE_* CLI smoke-harness variables
This commit is contained in:
Xiangzhe
2026-08-18 17:26:19 -03:00
parent df90591415
commit 40e8084b8c
7 changed files with 94 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.env.example
View File

@@ -761,7 +761,7 @@ NEXT_PUBLIC_ENABLE_SOCKS5_PROXY=true
# CLI_CURSOR_BIN=agent
# CLI_CLINE_BIN=cline
# CLI_CONTINUE_BIN=cn
# CLI_QODER_BIN=qoder
# CLI_QODER_BIN=qodercli
# CLI_QWEN_BIN=qwen
# CLI_AIDER_BIN=aider
# CLI_GOOSE_BIN=goose

2
docs/getting-started/QUICK-START.md
View File

@@ -140,6 +140,8 @@ omniroute launch-codex --model auto
You can do this manually via `codex` and command line parameters to specify endpoint and api key, but with the above command, OmniRoute takes care of everything for you.
The same one-command launch works for other CLIs via the generic launcher — `omniroute run <target>` supports `claude`, `codex`, `aider`, `goose`, `opencode`, `qwen`, and `gemini` (see [CLI Integrations](../guides/CLI-INTEGRATIONS.md)).
3. The CLI should be sending requests to OmniRoute now.
### Confirm your tool is routing to OmniRoute

30
docs/guides/CLI-INTEGRATIONS.md
View File

@@ -14,9 +14,15 @@ OmniRoute (local or remote) and writes the tool's own config file on **your**
machine. The API key is referenced by an environment variable wherever the tool
supports it. Commands that persist a tool-local environment file are noted below.
There are also two launchers — `omniroute launch` (Claude Code) and
`omniroute launch-codex` (Codex) — that spawn the CLI with the right env injected,
without writing any config at all.
There is also a generic launcher — `omniroute run <target>` — that spawns
`claude`, `codex`, `aider`, `goose`, `opencode`, `qwen` or `gemini` with the
right env injected, without writing any config at all. Targets and their
aliases come from the canonical manifest `bin/cli/cli-manifest.mjs`
(`claude-code|cc|anthropic`, `codex-cli|openai-codex|openai`, `goose-cli`,
`open-code`, `qwen-code`, `gemini-cli`), and `omniroute completion` offers the
same manifest-derived target words. The legacy per-tool launchers —
`omniroute launch` (Claude Code) and `omniroute launch-codex` (Codex) — remain
available.
Provider onboarding is available from the same local/remote context. The
API-first commands below keep management authentication separate from provider
@@ -87,8 +93,21 @@ Notes on flags (verified in the command source):
model auto-discovery: Cline, Kilo, Roo, Goose, Qwen, Aider. Those tools
also accept `--yes` for non-interactive runs (which then requires `--model`).
`setup-opencode` takes `--model` to set the default top-level model.
- `--model <id>` on `omniroute run` follows the manifest's per-target wiring
(`bin/cli/cli-manifest.mjs`): **aider** receives `--model openai/<id>` and
**opencode** `--model omniroute/<id>` (the prefix is added only when the id
does not already carry it); **qwen** and **gemini** receive the id verbatim;
**claude** gets it via `ANTHROPIC_MODEL`, **goose** via `GOOSE_MODEL`, and
**codex** via `-c model_providers.omniroute.*` args. **Qwen is the only run
target that hard-requires `--model`** — `omniroute run qwen` without it exits
`2` with an explicit error.
- `--port <port>` — local OmniRoute port (default `20128`, ignored when `--remote`
is set). Present on all `setup-*` and both launchers.
- `omniroute run` exit codes: the child CLI's own exit code is propagated
verbatim; `2` = invalid arguments (unsupported target, missing required
`--model`, container guard); `127` = the target binary is not in `PATH`;
`130`/`143`/`129` when the launch is ended by `SIGINT`/`SIGTERM`/`SIGHUP`;
`1` = other runtime launch failure.
- The two launchers (`launch`, `launch-codex`) accept `--profile <name>` to select
a profile written by `setup-claude` / `setup-codex`, plus pass-through args for
the underlying `claude` / `codex` binary.
@@ -251,6 +270,11 @@ Gemini surface (`/v1beta`). `omniroute run gemini` wires that automatically:
- a **temporary isolated `GEMINI_CLI_HOME`** whose `.gemini/settings.json`
selects `gemini-api-key` auth, so a stored Google OAuth session (Code Assist)
never overrides the OmniRoute-directed launch — removed after exit;
- **env hygiene**: the child env is scrubbed of `GOOGLE_API_KEY`,
`GOOGLE_GENAI_USE_VERTEXAI` and `GOOGLE_GENAI_USE_GCA` (which would redirect
auth to Vertex/Code Assist), and `GEMINI_DEFAULT_AUTH_TYPE=gemini-api-key` is
set as a belt-and-suspenders fallback — the other `run` targets get the same
treatment for their own conflicting variables;
- `--model <id>` injection from `--provider`/`--model`.
```bash

11
docs/guides/CODEX-CLI-CONFIGURATION.md
View File

@@ -319,6 +319,17 @@ omniroute launch-codex --remote http://100.x.x.x:20128/v1 --api-key sk-xxx
omniroute launch-codex --profile glm52 -- --yolo "fix this bug"
```
Codex is also a target of the two generic manifest-driven entry points
(`bin/cli/cli-manifest.mjs`):
```bash
# Interactive model picker → writes ~/.codex/<name>.config.toml (TOML, env_key)
omniroute configure codex
# Launch codex with the omniroute provider injected via -c flags (no config written)
omniroute run codex
```
---
## New Codex CLI features (v0.138–v0.141)

8
docs/guides/SETUP_GUIDE.md
View File

@@ -186,9 +186,11 @@ omniroute setup-qwen # ~/.qwen/settings.json + ~/.qwen/.env
```
Each accepts `--remote <url> --api-key <key>` to configure a local tool against a
**remote** OmniRoute, plus `--dry-run` to preview. The launchers
`omniroute launch` (Claude Code) and `omniroute launch-codex` (Codex) spawn the CLI
with the right env injected, writing no config at all.
**remote** OmniRoute, plus `--dry-run` to preview. To launch a CLI with the right
env injected and no config written at all, use the generic launcher
`omniroute run <target>` (claude, codex, aider, goose, opencode, qwen, gemini);
the legacy per-tool launchers `omniroute launch` (Claude Code) and
`omniroute launch-codex` (Codex) remain available.
For the full table (what each command writes, every flag, local vs remote, base-URL
`/v1` conventions), see **[CLI Integrations](./CLI-INTEGRATIONS.md)**.

81
docs/reference/CLI-TOOLS.md
View File

@@ -12,8 +12,8 @@ OmniRoute integrates with three categories of CLI tools spread across three dedi
| Page | Route | Concept | Count |
| -------------- | ----------------------- | ------------------------------------------------------------------------- | ------------ |
| **CLI Code's** | `/dashboard/cli-code` | Coding tools you point at OmniRoute (Client → CLI → OmniRoute → Provider) | 21 |
| **CLI Agents** | `/dashboard/cli-agents` | Autonomous agents you point at OmniRoute (same flow, broader scope) | 6 |
| **CLI Code's** | `/dashboard/cli-code` | Coding tools you point at OmniRoute (Client → CLI → OmniRoute → Provider) | 26 |
| **CLI Agents** | `/dashboard/cli-agents` | Autonomous agents you point at OmniRoute (same flow, broader scope) | 8 |
| **ACP Agents** | `/dashboard/acp-agents` | CLIs that OmniRoute spawns as backend via stdio/ACP (reverse flow) | see registry |
Legacy routes redirect via 308: `/dashboard/cli-tools` → `/dashboard/cli-code`, `/dashboard/agents` → `/dashboard/acp-agents`.
@@ -60,10 +60,14 @@ omniroute setup-goose omniroute setup-qwen omniroute setup-aider
Each accepts `--remote <url> --api-key <key>` (configure a local tool against a
remote OmniRoute), `--dry-run` (preview without writing), and `--port`. Tools
without model auto-discovery (Cline, Kilo, Roo, Goose, Aider, Gemini) take
`--model <id>` (and `--yes` for non-interactive runs). The launchers
`omniroute launch` (Claude Code) and `omniroute launch-codex` (Codex) spawn the CLI
with the right env injected and write no config at all.
without model auto-discovery (Cline, Kilo, Roo, Goose, Aider, Qwen) take
`--model <id>` (and `--yes` for non-interactive runs). To launch a CLI with the
right env injected and no config written at all, use the generic
`omniroute run <target>` launcher (claude, codex, aider, goose, opencode, qwen,
gemini — targets and aliases come from `bin/cli/cli-manifest.mjs`); the legacy
per-tool launchers `omniroute launch` (Claude Code) and `omniroute launch-codex`
(Codex) remain available. Gemini CLI is launch-only: it is an `omniroute run`
target but has no `setup-*`/`configure` recipe.
> **Full reference:** the master table — what each command writes, every flag,
> local vs remote, and which tools want a `/v1` suffix — lives in
@@ -86,8 +90,9 @@ the server. See
The dashboard's **apply endpoint** (`POST /api/cli-tools/apply`) enforces the
same guard: in a container, a write whose target is not bind-mounted from the
host answers **`422`** with `containerEphemeralTarget: true`, the safe error
text and a `hostSetupCommand` (e.g. `omniroute setup-opencode`) to run on the
host instead — nothing is written. `dryRun: true` keeps working in container
text and — for the tools with a host recipe (claude, codex, opencode, cline,
kilo, continue) — a `hostSetupCommand` (e.g. `omniroute setup-opencode`) to run
on the host instead; nothing is written. `dryRun: true` keeps working in container
mode and returns the generated content + target path without touching disk, so
you can preview from the dashboard and apply on the host. This behavior is
intentional and regression-guarded by
@@ -135,37 +140,38 @@ one surface without the others fails the suite instead of drifting silently.
---
## 1. CLI Code's Catalog (25 tools)
## 1. CLI Code's Catalog (26 tools)
All tools that appear in `/dashboard/cli-code`. Those with `baseUrlSupport: none` are wired through MITM or a manual guide instead of a custom base URL:
| id | name | vendor | baseUrlSupport | configType | acpSpawnable |
| ------------ | -------------------- | ------------------- | -------------- | -------------- | ------------ |
| claude | Claude Code | Anthropic | full | env | true |
| codex | OpenAI Codex CLI | OpenAI | full | custom | true |
| cline | Cline | OSS (ex-Claude Dev) | full | custom | true |
| kilo | Kilo Code | Kilo-Org | full | custom | false |
| roo | Roo Code | Roo (OSS) | full | guide | false |
| continue | Continue | continue.dev | full | guide | false |
| aider | Aider | OSS (P. Gauthier) | full | guide | true |
| forge | ForgeCode | Antinomy HQ | full | custom | true |
| jcode | jcode | 1jehuang (OSS) | full | custom | false |
| deepseek-tui | DeepSeek TUI | Hunter Bown (OSS) | full | custom | false |
| codewhale | CodeWhale | Hmbown (OSS) | full | custom | false |
| opencode | OpenCode | Anomaly (ex-SST) | full | guide | true |
| droid | Factory Droid | Factory AI | partial | guide | false |
| copilot | GitHub Copilot CLI | GitHub/MS | full | custom | false |
| cursor-cli | Cursor CLI | Anysphere | partial | guide | true |
| smelt | Smelt | leonardcser (OSS) | full | custom | false |
| pi | Pi (pi-coding-agent) | M. Zechner (OSS) | full | custom | false |
| grok-build | Grok Build | xAI | full | custom | false |
| crush | Crush | OSS (Charm) | full | custom | false |
| qwen | Qwen Code | Alibaba | full | guide | true |
| cursor | Cursor | Anysphere | none | guide | false |
| antigravity | Antigravity | Google | none | mitm | false |
| hermes | Hermes | Nous Research | none | guide | false |
| kiro | Kiro AI | Amazon | none | mitm | false |
| custom | Custom CLI | — | full | custom-builder | false |
| id | name | vendor | baseUrlSupport | configType | acpSpawnable |
| ------------ | ----------------------- | ------------------- | -------------- | -------------- | ------------ |
| claude | Claude Code | Anthropic | full | env | true |
| codex | OpenAI Codex CLI | OpenAI | full | custom | true |
| zcode | ZCode (GLM Coding Plan) | Z.ai | none | custom | false |
| cline | Cline | OSS (ex-Claude Dev) | full | custom | true |
| kilo | Kilo Code | Kilo-Org | full | custom | false |
| roo | Roo Code | Roo (OSS) | full | guide | false |
| continue | Continue | continue.dev | full | guide | false |
| aider | Aider | OSS (P. Gauthier) | full | guide | true |
| forge | ForgeCode | Antinomy HQ | full | custom | true |
| jcode | jcode | 1jehuang (OSS) | full | custom | false |
| deepseek-tui | DeepSeek TUI | Hunter Bown (OSS) | full | custom | false |
| codewhale | CodeWhale | Hmbown (OSS) | full | custom | false |
| opencode | OpenCode | Anomaly (ex-SST) | full | guide | true |
| droid | Factory Droid | Factory AI | partial | guide | false |
| copilot | GitHub Copilot CLI | GitHub/MS | full | custom | false |
| cursor-cli | Cursor CLI | Anysphere | partial | guide | true |
| smelt | Smelt | leonardcser (OSS) | full | custom | false |
| pi | Pi (pi-coding-agent) | M. Zechner (OSS) | full | custom | false |
| grok-build | Grok Build | xAI | full | custom | false |
| crush | Crush | OSS (Charm) | full | custom | false |
| qwen | Qwen Code | Alibaba | full | guide | true |
| cursor | Cursor | Anysphere | none | guide | false |
| antigravity | Antigravity | Google | none | mitm | false |
| hermes | Hermes | Nous Research | none | guide | false |
| kiro | Kiro AI | Amazon | none | mitm | false |
| custom | Custom CLI | — | full | custom-builder | false |
Tools with `baseUrlSupport: "partial"` show a badge "⚠ Base URL parcial" in the dashboard card.
---
@@ -385,7 +391,8 @@ export OPENAI_BASE_URL="http://localhost:20128/v1"
export OPENAI_API_KEY="sk-your-omniroute-key"
export ANTHROPIC_BASE_URL="http://localhost:20128"
export ANTHROPIC_AUTH_TOKEN="sk-your-omniroute-key"
export GEMINI_BASE_URL="http://localhost:20128/v1"
# Gemini CLI reads GOOGLE_GEMINI_BASE_URL at the ROOT (its SDK appends /v1beta/... itself)
export GOOGLE_GEMINI_BASE_URL="http://localhost:20128"
export GEMINI_API_KEY="sk-your-omniroute-key"
```

8
docs/reference/ENVIRONMENT.md
View File

@@ -87,7 +87,7 @@ OmniRoute uses **SQLite** (via `better-sqlite3`) for all persistence. These vari
| `OMNIROUTE_BUILD_SHA` | _(unset)_ | `src/lib/monitoring/buildSha.ts` | Git SHA of the running artifact. Stamped by `npm run build:release`; injectable in containers that ship without the `dist/BUILD_SHA` sentinel. Surfaced as `system.buildSha` on `/api/monitoring/health`. |
| `OMNIROUTE_RELEASE_REF` | `origin/main` | `scripts/build/buildProvenance.ts` | Ref the pack-artifact provenance gate checks the build SHA against (#10427). |
| `OMNIROUTE_ALLOW_CANARY_BUILD` | _(unset)_ | `scripts/build/buildProvenance.ts` | Set to `1` to allow packing a build whose SHA is not on the release line, recording it as a deliberate canary instead of failing the gate (#10427). |
| `OMNIROUTE_SMOKE_API_KEY` | _(unset)_ | `scripts/ops/deploy-canary.mjs` | API key for the canary-deploy smoke probe, sent as `Authorization: Bearer` on `/v1/chat/completions`. Only used by the deploy script (#10429), never by the server. |
| `OMNIROUTE_SMOKE_API_KEY` | _(unset)_ | `scripts/ops/deploy-canary.mjs` | API key for the canary-deploy smoke probe, sent as `Authorization: Bearer` on `/v1/chat/completions`. Only used by the deploy script (#10429), never by the server. Not related to the `OMNIROUTE_SMOKE_*` variables of the opt-in CLI smoke harness (`RUN_CLI_SMOKE=1`, `OMNIROUTE_SMOKE_BASE_URL/MODEL/API_KEY_ENV/TARGETS/TIMEOUT_MS` in `tests/integration/upstream-cli-smoke.int.test.ts`) — see [CLI Integrations → Real smoke sweep](../guides/CLI-INTEGRATIONS.md). |
| `OMNIROUTE_DATA_DIR` | _(unset)_ | `open-sse/executors/promptql/threadSticky.ts` | **Fallback alias** for `DATA_DIR`, checked only when `DATA_DIR` is unset. Used to locate the PromptQL executor's on-disk thread-sticky session cache (`<dir>/promptql-thread-sessions.json`); if neither var is set, the cache stays in-memory only (not persisted across restarts). |
| `STORAGE_ENCRYPTION_KEY` | _(empty = disabled)_ | `src/lib/db/encryption.ts` | AES key for full SQLite database encryption at rest. Generate with `openssl rand -hex 32`. |
| `STORAGE_ENCRYPTION_KEY_VERSION` | `v1` | `scripts/build/bootstrap-env.mjs`, `electron/main.js` | Version label for the encryption key. Increment when performing key rotation to support decryption of old backups. |
@@ -380,7 +380,7 @@ Controls how OmniRoute discovers and launches CLI sidecars (Claude Code, Codex,
| `CLI_MODE` | `auto` | `src/shared/services/cliRuntime.ts` | `auto` = search system PATH; `manual` = use explicit paths only. |
| `CLI_EXTRA_PATHS` | _(unset)_ | `src/shared/services/cliRuntime.ts` | Additional PATH entries for CLI binary discovery (colon-separated). |
| `CLI_CONFIG_HOME` | _(unset)_ | `src/shared/services/cliRuntime.ts` | Override home directory for reading CLI configs (`~/.claude`, `~/.codex`). Must be absolute and inside the process home — **or**, in a container, a bind-mounted path (that is how `/host-home` works). Anything else falls back to the home dir. |
| `CLI_ALLOW_CONFIG_WRITES` | `false` | `src/shared/services/cliRuntime.ts` | Allow OmniRoute to write CLI config files (token refresh, session data). |
| `CLI_ALLOW_CONFIG_WRITES` | `true` | `src/shared/services/cliRuntime.ts` | Allow OmniRoute to write CLI config files (token refresh, session data). Set to `false` to make every CLI config write fail with an explicit "writes disabled" error. |
| `CLI_CLAUDE_BIN` | `claude` | `src/shared/services/cliRuntime.ts` | Custom path to Claude CLI binary. |
| `CLI_CODEX_BIN` | `codex` | `src/shared/services/cliRuntime.ts` | Custom path to Codex CLI binary. |
| `CLI_DROID_BIN` | `droid` | `src/shared/services/cliRuntime.ts` | Custom path to Droid CLI binary. |
@@ -388,11 +388,11 @@ Controls how OmniRoute discovers and launches CLI sidecars (Claude Code, Codex,
| `CLI_CURSOR_BIN` | `agent` | `src/shared/services/cliRuntime.ts` | Custom path to Cursor agent binary. |
| `CLI_CLINE_BIN` | `cline` | `src/shared/services/cliRuntime.ts` | Custom path to Cline CLI binary. |
| `CLI_CONTINUE_BIN` | `cn` | `src/shared/services/cliRuntime.ts` | Custom path to Continue CLI binary. |
| `CLI_QODER_BIN` | `qoder` | `src/shared/services/cliRuntime.ts` | Custom path to Qoder CLI binary. |
| `CLI_QODER_BIN` | `qodercli` | `src/shared/services/cliRuntime.ts` | Custom path to Qoder CLI binary. |
| `CLI_QWEN_BIN` | `qwen` | `src/shared/services/cliRuntime.ts` | Custom path to the Qwen Code CLI binary. |
| `CLI_AIDER_BIN` | `aider` | `src/shared/services/cliRuntime.ts` | Custom path to the Aider CLI binary. |
| `CLI_GOOSE_BIN` | `goose` | `src/shared/services/cliRuntime.ts` | Custom path to the Goose CLI binary. |
| `CLI_GEMINI_BIN` | `gemini` | `src/shared/services/cliRuntime.ts` | Custom path to the Google Gemini CLI binary (used by detection and `omniroute run gemini`). |
| `CLI_GEMINI_BIN` | `gemini` | `src/shared/services/cliRuntime.ts` | Custom path to the Google Gemini CLI binary — server-side detection/health checks only; `omniroute run gemini` resolves the `gemini` binary from `PATH`. |
| `CLI_DEVIN_BIN` | `devin` | `open-sse/executors/devin-cli.ts` | Custom path to the Devin CLI binary (v3.8.0). Used by the Windsurf/Devin executor. |
| `DEVIN_DESKTOP_VERSION` | `3.6.27` | `open-sse/executors/devin-desktop.ts` | Devin Desktop `ide_version`. Overrides must use `x.y.z` format; invalid values fall back to the verified default. |
| `DEVIN_DESKTOP_EXTENSION_VERSION` | `1.48.2` | `open-sse/executors/devin-desktop.ts` | Bundled Codeium/language-server `extension_version`, distinct from Desktop `ide_version`. Overrides must use `x.y.z`; invalid values use the bundled default. |