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.
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
- 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.
- Exit the Codex instance using HiRoute. Open a terminal using the original
CODEX_HOMEshown in the connection's configuration details. Use the same original profile and working environment as before enabling HiRoute. - Run
codex resume --alland select the earlier session. If the original entry used an explicit profile, retain it:codex --profile <original-profile> resume --all. Thehirouteprofile is the managed route, not the original entry. - 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.