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.

12.4 KB
Raw Blame

macOS installation candidate

简体中文

The target is macOS 15+, with separate single-architecture packages for Apple Silicon (arm64) and Intel (x86_64). The minimum version comes from the actual build facts of the bundled official CPA release. Older macOS, real Intel hardware, and Windows require separate evidence and cannot be inferred from an arm64 run. The repository provides candidate-build entry points; a successful build is not Finder, account, Worker, or public-distribution acceptance.

Installation and CLI

Open the candidate DMG, drag HiRoute.app to its Applications shortcut, eject the image, and open /Applications/HiRoute.app. A ZIP remains available for direct extraction. A self-signed package may be blocked on first launch because it has no Developer ID notarization. An engineering candidate is not automatically suitable for public distribution; only the exact artifact that passes integrity, installation, component-disclosure, and release review and appears in the website manifest is a public download. Use a trusted package and follow the macOS application-open confirmation flow without disabling system security.

The app can install its per-user terminal entry only while running from /Applications/HiRoute.app or ~/Applications/HiRoute.app. In Settings → CLI, explicitly choose Install. HiRoute creates ~/.local/bin/hiroute as a symlink to the bundled CLI; it does not copy the binary, request sudo, or modify shell files. If that path already contains a non-HiRoute entry, installation reports a conflict and leaves it unchanged. The entry is not installed while the app runs from a DMG, download directory, or another location.

Ensure that ~/.local/bin is on PATH; zsh users can add this to ~/.zprofile:

export PATH="$HOME/.local/bin:$PATH"
hiroute worker list --output json
hiroute --help

Settings reports the symlink as missing/valid/broken/conflict, whether PATH includes its directory, whether an earlier command shadows it, and whether the daemon is available. A valid symlink does not prove the service is running. Repair/remove operates only on a HiRoute- owned link targeting a supported HiRoute.app; it never deletes ~/.local or ~/.local/bin. A managed Agent prepends ~/.local/bin to its subprocess PATH only after revalidating the link against the current trusted app CLI.

Managed Agent skills and launchers continue to use the hiroute command and existing integration Preview/confirmation flow. Running the app requires no Rust, Go, Docker, npm, or source checkout. A Worker's own CLI, ACP adapter, and required runtime follow the dependency guidance in Settings and are not bundled with HiRoute.

The CLI connects by default to ~/Library/Application Support/ai.hiroute.desktop/run. HIROUTE_RUNTIME_DIR takes precedence over XDG_RUNTIME_DIR; both are explicit development/test overrides. An empty or relative path is unavailable and never falls back to another instance. Open HiRoute when it is not running. After a service outage, restore Desktop and query with the original operation or task identity rather than resubmitting a request with an unknown outcome.

CPA is bundled and used only for authorized subscription paths. If it is missing, replaced, or not executable, subscription checks fail while control and other available API sources remain usable. Replace a damaged app with a complete candidate; do not install another CPA manually.

Manual upgrade and removal

Prefer Settings → Updates. The updater verifies the complete DMG/App, asks the verified candidate to check storage/recovery prerequisites before replacement, waits for current calls/tasks, and retains the complete previous App and handoff. Waiting can be cancelled. Storage startup repeats admission under its writer lock.

If you must replace an App manually, fully quit HiRoute and stop its owned service and tasks, keep the complete original App, and preserve the data directory. There is no recovery-package picker. A missing-package failure does not authorize program-only reinstallation or downgrade. Keep every data generation, key, complete App and upgrade journal. Open diagnostics and obtain support to verify the matching recovery material and supported upgrade route. Do not infer safety from a generic error or the absence of a backup directory.

If startup reports a resumable original batch, reopen the current version. For a mixed, modified, unsupported or uncertain group, do not launch an older App. Preserve every generation and follow the identified batch's RECOVERY.md or 恢复说明.md. Stop HiRoute, preserve newer data with its matching program separately, and restore the complete recorded old group and matching complete App at their original locations. Never replace individual databases or mix WAL/SHM, keys or backup batches. Newer records remain in the separately preserved group; they do not appear in the restored old group. Invalid/missing material or keys need correction/support, not repeated retries or data deletion.

Recovery instructions remain available on the startup failure page while the service is down. A verified resumable/restorable source shows its original batch ID and source directory. Use the preserved-material action, match the batch and read RECOVERY.md or 恢复说明.md before restoration. Unknown or unverified locations cannot authorize recovery. Offline hiroute service recovery --output json also names the verified batch and absolute source directory. Insufficient-space errors require freeing unrelated files; retain sealed history and recovery packages. A format-changing update keeps configuration, credentials and routing, seals old HiRoute observations, and starts current history/statistics at cutover. Native Agent history is unchanged.

The updater shipped by v0.3.1 launches its own installation helper. New preflight code cannot retrofit that helper. Use only the transition sequence validated for the source release; if no verified route is offered, keep the working installation and obtain support rather than bypassing a refusal with manual replacement.

If moving the App invalidates integration paths, use the integration Preview and confirmation in Settings, resolve user-configuration drift, and check the login item. Window disappearance alone does not establish service/task shutdown.

Before removal, Preview and restore managed model/Agent integration from Settings, disable background launch at login, explicitly quit, and delete the app. App deletion preserves data by default. For a complete data removal, first confirm that no task is running, integration has been restored, and sessions/logs/receipts are no longer needed; then delete only the current user's HiRoute data under ~/Library/Application Support/ai.hiroute.desktop. Never delete .codex, .claude, user projects, or existing credentials. If the app is damaged, restore a complete candidate to the same installation location before restoring integration; do not guess at configuration overrides by hand.

Build and checks

Run from the exact clean committed checkout on macOS (the host architecture by default):

RUSTC_WRAPPER=sccache python3 scripts/package-desktop.py build \
  --arch arm64 --cpa-source-repo /path/to/CLIProxyAPI
# Use the actual paths reported by the build:
python3 scripts/package-desktop.py verify /absolute/output/HiRoute.app
python3 scripts/package-desktop.py verify-dmg /absolute/output/HiRoute-VERSION-SHA-macos-arm64-trial.dmg

The build reuses the existing shared Rust-validation lock and keeps output in this checkout's target/. Even with sccache, never move the Cargo target. Packaging performs a locked release build and frontend build; ordinary development validation remains Debug.

From the explicitly supplied CPA checkout, the tool resolves the commit pinned by vendor/cpa/source.json, verifies and applies the adjacent launch-pipe patch, builds with Go, signs CPA, and compiles the final digest manifest into Desktop. It never performs deep resigning. The patch only lets the parent pass existing instance-management credentials over an inherited pipe; loopback and remote-management-disabled rules remain intact and the model protocol is unchanged. The build host needs Go and access to locked Go dependencies. An arbitrary prebuilt CPA is rejected and nothing is downloaded at user startup.

The upstream license is installed as Licenses/CLIProxyAPI-LICENSE; source, patch, compiler, and artifact digests appear in build evidence. The packager also generates THIRD-PARTY-LICENSES.txt and a machine-verifiable manifest from locked Cargo/npm dependencies and the same CPA commit, placing them with HiRoute's Apache-2.0 license under Contents/Resources/Licenses. Missing verifiable license material aborts the build.

Intel uses --arch x86_64 and requires the x86_64-apple-darwin Rust target. Apple Silicon uses --arch arm64 and aarch64-apple-darwin. A cross-build must be able to execute the target CPA version probe (Apple Silicon therefore needs an existing Rosetta installation for Intel); the tool never installs Rosetta. Architectures have independent output under target/desktop-package/CANDIDATE_SHA/ARCH/ROUND/; components are not mixed and no universal binary is synthesized.

Rerun the same command for another round. UTC time and a random suffix keep rounds separate without overwriting artifacts or cleaning target/. DMG/ZIP names contain version, twelve commit characters, architecture, and either trial or developer-id. Each result.json contains the full commit, DMG/ZIP SHA-256, component digests, and image checks; build.log retains command output. The DMG is a compressed read-only image built with hdiutil, then checked for integrity, a read-only mount entry, and app components before being detached. If detach fails, packaging fails and logs the mount path. Close windows using that path and run hdiutil detach PATH; never forcibly detach another image.

For manual review, first compare shasum -a 256 FILE.dmg with the round's result.json, then install as described above. Quit the old app before replacement. Use a separate macOS test account for an initial isolated check when possible, and do not present success under a development override as ordinary Finder-launch acceptance. Record the complete commit (also in Contents/Resources/installation.json), DMG SHA-256, architecture, macOS version, reproduction steps, and actual result. If macOS blocks launch, record the message and approve the trusted app through System Settings → Privacy & Security. Do not remove quarantine attributes or disable Gatekeeper/SIP. An ad-hoc build may still require manual approval, and a successful build does not guarantee launch.

The native host, daemon, CLI, and CPA are in Contents/MacOS; the current model catalog is compiled into the daemon and frontend assets into the host. Contents/Resources/installation.json records candidate commit, version, final digests, and system dynamic dependencies. dependency-inventory.json is an attribution-review inventory, including Cargo dependencies that may not be linked, and does not replace license texts.

A Developer ID candidate uses an existing notarization keychain profile while collecting component licenses through the same locked process:

python3 scripts/package-desktop.py build \
  --cpa-source-repo /path/to/CLIProxyAPI \
  --identity 'Developer ID Application: YOUR ORGANIZATION (TEAMID)' \
  --notary-profile YOUR_PROFILE

Credentials come only from the local keychain and never enter the repository or command output. The tool signs nested binaries and the app, submits and staples notarization, rebuilds the ZIP, then packages, signs, and notarizes the DMG; both notarizations must be Accepted. Self-signed builds are marked controlled-trial and make no Developer ID or notarization claim. That technical marker alone does not establish component disclosure, installation, or release review. Near-term public self-signed releases still require explicit applicable component material and all release-manifest gates.

Record installation evidence separately for installation location/Finder launch without overwrite; CLI access to the same service and not-running errors; real delegation/results; authorized subscription calls; health/control behavior when CPA is missing, replaced, or fails; login launch; quit; manual upgrade; and recoverable removal. Include the exact commit, package digest, and actual result. Component and fixture tests cannot replace this evidence.