Skip to content

Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.

10.8 KB
Raw Blame

Local configuration saves

HiRoute's Local Control socket uses the operating system's local access permissions. HiRoute adds no file-owner, permission-bit or peer-UID admission check. New private files and directories still default to 0600/0700. Desktop and CLI use this local scope for configuration saves and Operation recovery. They do not need a Desktop/CLI-specific Apply capability or a second authorization confirmation. A Save, Publish, or Use this installation click is the ordinary user intent.

The daemon still validates the exact normalized change, digest, resource revisions, idempotency key, and durable writer admission. On a conflict, refresh the current state and submit the intended edit again. If a response is lost, first query or replay the same operation identity; do not invent a new key or assume that a missing response means failure.

This local trust decision does not authorize remote Agent collaboration, Gateway calls, or potentially billable model checks. Those flows keep their own consent and credential boundaries. The Desktop WebView can only use its explicitly exposed native commands and cannot supply an arbitrary Local Control request.

The routing editor displays the current head's call state separately from unsaved edits and saved drafts. A disabled route remains visibly stopped even while its configuration is being edited; only a successful lifecycle change enables calls.

Codex CLI profile

For an isolated instance, set HOME and CODEX_HOME to its private directories. HIROUTE_CODEX_AUTH_SOURCE may independently select an absolute, readable Codex auth.json for subscription discovery and CPA's access-only lease. Set it on the process that starts the daemon. Without this override, the source remains CODEX_HOME/auth.json (or HOME/.codex/auth.json). An explicit invalid or missing source never falls back to another account. Discovery and CPA use the same source; the override does not select the native Agent configuration or Worker history root. CPA never receives the source's refresh token and never refreshes or rewrites the source. The original Codex retains refresh ownership.

Independent sign-in through HiRoute is the recommended Codex and Claude subscription entry; CPA then owns that authorization and refresh. When reusing Codex's native login without an explicit auth-file override, HiRoute accepts file storage only. A non-file cli_auth_credentials_store selection is reported as unsupported even if an old auth.json remains. Use independent sign-in in that case. Borrowing requires a current access token and an identifiable account; an ID token or refresh timestamp is not required.

An isolated acceptance process must also clear inherited provider credentials, model-routing variables and Claude context overrides. A private HOME alone does not remove higher-precedence process settings. A settings preview must explain missing effective-configuration or safe-write evidence without exposing settings values; it must not bypass those checks to make a save succeed.

The default Codex connection owns one hiroute.config.toml profile in the detected original CODEX_HOME. It preserves config.toml and the ordinary CLI/Desktop default provider. Copy the launch command from the Agent page and select your shell. The command explicitly sets the detected CODEX_HOME for that invocation because a newly opened terminal may have another environment; it does not change HOME or your shell configuration.

One canonical CODEX_HOME supports one managed model connection: either this CLI profile or the advanced default-configuration takeover. The advanced mode changes the default provider for ordinary Codex and Desktop using that home. To switch, restore the current model settings, finish any pending cleanup, and then configure the other mode. An existing unowned profile or an inherited model_providers.hiroute/profiles.hiroute entry is a conflict; HiRoute does not adopt files by name or remove their authentication fields. Preserve your own files and resolve the conflicting entry manually before a fresh preview.

Profile mode uses native codex --profile hiroute; it does not provide a Desktop profile launcher. Session histories remain scoped to their native provider; HiRoute does not merge histories or modify the session database. Gateway credentials authorize the selected models independently of the Codex client's OpenAI login; retaining original models still requires a usable upstream source configured in HiRoute.

A pending operation reserves the home even if Gateway access is already revoked. The Agent page shows the target and conflicting fields, and can recheck and resume the original Operation. Save your edits before repairing the file. A file change after the operation was staged, including formatting, must be undone before retry; after cleanup you can reapply unrelated edits. HiRoute never force-overwrites a conflict. A newly created profile containing user-added settings is retained after the managed fields are removed.

Local CLI callers can resume that same operation through agents connect apply with:

{"schema":"hiroute.agent-settings-retry/v1","context_id":"<discovered context>","operation_id":"<pending Operation>"}

This retry accepts no new settings or grants. The daemon checks the stored operation and its context before continuing. First-time creation and edits still require normal Preview/Apply.

Find earlier Codex sessions

Default On demand mode preserves ordinary Codex configuration and session history. Use the ordinary Codex entry to find earlier sessions; the HiRoute profile can remain enabled.

Inside the HiRoute profile, Codex filters its native /resume picker by HiRoute's model provider. Sessions created with another provider can disappear from that picker while their files remain in the same CODEX_HOME. Advanced Use by default mode applies this provider change to ordinary Codex and Desktop as well. Selecting all directories, or running codex resume --all, removes the directory filter; it does not remove the provider filter. The model-routing form and configured connection explain the selected mode's scope and return path.

Return to the original provider

  1. For default On demand mode, return to the ordinary Codex entry without the HiRoute profile. No disable or configuration restoration is needed. For advanced Use by default mode, open Agents → Codex in HiRoute and turn off Model routing first. Wait for configuration restoration to complete; resolve any reported file conflict or incomplete operation before continuing.
  2. Exit the Codex instance using HiRoute. Open a terminal using the original CODEX_HOME shown in the connection's configuration details. Use the same original profile and working environment as before enabling HiRoute.
  3. Run codex resume --all and select the earlier session. If the original entry used an explicit profile, retain it: codex --profile <original-profile> resume --all. The hiroute profile is the managed route, not the original entry.
  4. Continuing the session uses the original provider and its account or API credentials. Those requests bypass HiRoute. The on-demand HiRoute profile remains available for separate sessions. Advanced default takeover changes the ordinary entry's provider again when re-enabled.

Advanced-mode restoration uses the existing conditional transaction for HiRoute-owned configuration fields. Neither return path edits Codex's session files, provider labels or private session database. Keep a backup of important history; changing provider IDs or rewriting the database is not a supported migration.

For sessions created under several different original providers, use each provider's original configuration and credentials. HiRoute cannot reconstruct a configuration or account that was already missing before it was enabled.

The native commands are documented in the official Codex CLI reference. The configuration contract belongs to Agent connections.

OpenCode

In Agents, enable OpenCode model routing and select the published routes and each route's Responses or Messages protocol. Save, restart ordinary OpenCode in the selected native context, and choose an added route in its model picker. Native default/small-model choices and other providers remain independent. A model or agent setting that still references an owned route must be changed before that route can be removed; rotating its token can retain the same selector.

Once configured, model edits and recovery retain the original native file. Adding an opencode.jsonc beside a managed opencode.json does not move that binding. An effective user layer that overrides or disables an owned provider is reported as configuration drift; unrelated settings can change independently.

Dynamic configuration keys are unavailable for managed model settings, static API import and Workers. A model choice expressed through an environment/file substitution must become an explicit native selector before removing a route it could reference. Keeping all current selectors can still rotate their token. These limits do not prevent independent Skill installation. Static import also leaves unresolved model-ID substitutions unavailable rather than importing the substitution text as an upstream model name.

Task collaboration installs the shared hiroute-collaboration Skill independently of model routing. It can be enabled with no published route or model connection. Model restore and Skill restore are separate actions. The prerequisite check proves native Skill/CLI capability; completed delegated work has its own task result.

Worker installation is selected in the route editor using one native OpenCode CLI. The initial supported history format is the official npm platform package for OpenCode 1.19.3. Detection can resolve a unique official npm launcher to that native executable without running the launcher. Other installation forms can retain independent model configuration and Skill capabilities.

The daemon uses the selected native HOME/XDG context, optional absolute OPENCODE_CONFIG, additive OPENCODE_CONFIG_DIR, and native database location. Set context selectors on the process that starts HiRoute. Continue retains the original workspace, context, native session and route with fresh run credentials; changing today's environment does not select another conversation. Worker XDG roots must still map to the native opencode directory after canonical resolution. A directory link to a differently named leaf is unavailable for Worker launch and Continue; it does not disable ordinary settings or Skill installation.

OpenCode Go uses ordinary API-source setup or a supported static import. Its API key does not create a HiRoute subscription/CPA login or quota-management entry.