Desktop Client Guide: Environments, One-Click Setup, and Pricing

What this is

OpenTokenRouter Desktop is a desktop client for gateway administrators and developers. It does three things:

1. Multi-environment management: keep dev, staging, production, or customer instances in one client. Credentials live only in the system keychain; switch, clone, import, and export environments freely.
2. One-click local CLI setup: apply an environment + model + Codex CLI / Claude Code combination to your machine without touching existing OpenAI / Claude configuration.
3. Pricing management: pull current pricing from an environment as a baseline, edit model prices and group ratios, estimate costs, and deploy the result to any environment. Every deploy can be rolled back.

This guide is the advanced companion to the Client Setup guide: that one covers manual configuration, this one covers the full desktop client workflow.

Download and install

1. Open the Download page and get the installer for your platform: macOS (DMG), Windows, or Linux.
2. macOS: open the DMG and drag OpenTokenRouter into Applications. If Gatekeeper blocks the app (installers are unsigned preview builds), open System Settings → Privacy & Security and click Open Anyway.
3. Windows: run the installer and keep the default per-user installation. If SmartScreen appears, click More info → Run anyway.
4. Only download installers from the official Download page; never run copies from unknown sources.

Core concepts

Environments

Add an environment

On the Environments page click Add environment and fill in:

• Name: e.g. production / staging / customer A.
• Gateway origin: production must use HTTPS; only localhost / 127.0.0.1 may use HTTP. No userinfo, path, or query strings are allowed.
• API Key: stored only in the system keychain, never in local files or exports.
• Default model (optional): the environment default; still editable when applying configuration.

After saving, click Probe to request server info and see connectivity, latency, and model count. You may save even if probing fails; the environment is then marked as failed to probe.

Active environment

Any environment can be set as active. One-click setup and pricing editing target the active environment by default; switches are recorded in the local audit log.

Clone, import, and export

• Clone: duplicate an environment to quickly stand up a similar instance.
• Export: export to JSON (name, origin, type, default model, etc.). API keys are never exported, so files are safe to share or back up.
• Import: paste an exported JSON; credentials are not imported, so you must add an API key per environment afterwards (status shows missing credential).

Delete an environment

Deleting removes the environment and its keychain credential. Export first if you might need it again.

One-click setup for Codex CLI and Claude Code

Prepare tools

The setup flow detects whether codex / claude are installed and can install the official CLI for you.

Choose a model

After selecting an environment, the client lists its available models filtered by the target's endpoint type (Codex needs openai-response endpoints, Claude Code needs anthropic), so you cannot pick a protocol-incompatible model.

Preview and apply

Preview the configuration before applying it, then click Apply. What gets written:

• Codex CLI: a dedicated OpenTokenRouter profile; ~/.codex/config.toml is not modified. Start with --profile opentokenrouter.
• Claude Code: a dedicated CLAUDE_CONFIG_DIR; existing Claude login is not touched.

A local backup is created automatically before every apply (see Backups below).

Switch environments

After switching the active environment, run Apply again to point Codex / Claude Code at the new environment; preview first to confirm the target origin and model.

Pricing management

Pull pricing

On the Pricing page select the target environment and click Pull pricing. The client reads the environment's billing whitelist (ModelRatio, ModelPrice, GroupRatio, GroupGroupRatio, QuotaPerUnit, etc.).

Save a baseline profile

Save the pulled result as a baseline profile. Profiles support new, save, load, delete, and diff (secret-like fields are shown as REDACTED).

Editor

• Model price table: per model — unit price ($/1M), ratio, cache read ratio, cache write ratio, completion ratio, image ratio, and billing mode.
• Group ratios: per group — top-up ratio and description.

Estimator

Inputs: prompt tokens, completion tokens, cache read tokens, cache write tokens, and group ratio. Click Calculate for estimated quota and estimated cost; the formula matches the gateway's service/text_quota.go.

Deploy and rollback

Before deploying the editor contents to a target environment, the client shows the exact options that will be written. Confirm to deploy key by key; failures can be retried. A pricing snapshot is created before every deploy, and the Deploy and rollback section offers one-click rollback.

Backups and rollback

The Backups page lists configuration transaction history: a local backup is created before every apply / deploy, and you can roll back to a backup. Rollback restores configuration files only; revoked keys are not restored. If the current file was modified externally, the client will refuse to overwrite it.

Diagnostics

The Diagnostics page shows platform and architecture, local tool detection, secure storage and config paths, and the pinned terminal command, with one-click Refresh. Diagnostics never include API keys, so screenshots are safe to share with support.

Security

• Environment credentials live only in the system keychain; local storage, exports, audit logs, and pricing snapshots never contain keys.
• Import/export and profile diffs never leak secrets (sensitive fields show REDACTED).
• Active-environment switches, deploys, and rollbacks are written to the local audit log.

Updates

The client checks for updates automatically:

1. A silent check runs at startup; the About page also has a manual Check for updates button.
2. When a new version is available, click Download update — the installer is saved to ~/.opentokenrouter/downloads/.
3. After the download finishes, click Open installer and complete the upgrade with the system installer (drag to Applications on macOS / run the setup on Windows).

The update server defaults to the official gateway origin and can be changed in About → Updates (it must point at an OpenTokenRouter gateway serving /api/status).

Unsigned preview builds require right-click open / "Open Anyway" on macOS and "Run anyway" in Windows SmartScreen.

FAQ

macOS cannot open the app / says it is damaged

Installers are unsigned preview builds: open System Settings → Privacy & Security → Open Anyway, and make sure you downloaded from the official Download page.

Windows SmartScreen blocks the installer

Click More info → Run anyway.

Probing a new environment fails

Check the protocol (production must be HTTPS), that the origin has no path or query string, and that the API key has permission. The Diagnostics page can help verify local network and proxy settings.

The model list is empty

Confirm the active environment has a saved credential and probes successfully, and that it exposes callable models (marked Live settlement on the home page).

After applying, the CLI still uses the old environment

You must run Apply again after switching the active environment; preview first to confirm the target origin and model.

Rollback says the file was modified externally

The target config file was changed by another tool after apply. The client will not overwrite external changes; back up your edits and merge manually.