Harness integrations
What the Hermes, OpenClaw, Claude Code, and Codex installers change, verify, and protect. Operational setup lives in Integrations.
Omnious has first-party setup paths for Hermes, OpenClaw, Claude Code, Codex, OpenCode, pi, and OMP. The executable flow lives in the app, where the same wallet session can approve a bounded key, show its unified API balance, top it up, and revoke it later. These docs explain the guarantees and local changes without creating a second account or funding surface.
Open harness setup in Integrations →
One flow, end to end
- Choose a harness. Integrations generates the shortest safe terminal command for it.
- Run the command locally. The CLI first confirms the selected harness is installed. On macOS, Linux, and WSL, missing Hermes triggers an explicit prompt before the official installer runs. Only then does it create a short-lived device session and open the app. Its device credential stays in that terminal process.
- Confirm and approve. The app shows the exact harness, environment, key label, rolling budget, and expiry before one gas-free wallet signature.
- Fund and manage in place. The approved key draws from the wallet-owned unified API balance shown beside setup. Top-up and revocation remain on the same page.
- Start in the right profile. After compatibility checks pass, the CLI opens the harness with its Omnious profile already active. Use
--no-launchfor scripts or headless setup.
What the installer changes
| Harness | Install mode | Existing setup |
|---|---|---|
| Hermes | Installs a standalone native omnious model-provider profile under the active Hermes profile, independent of chat channel, keeps auto selected, discovers every available model for its native picker, and adds the read-only /omnious-rfq command. | Checks for the Hermes CLI before wallet approval; on macOS, Linux, and WSL, a missing CLI makes the terminal ask before running Nous Research's official installer. It does not patch Hermes core, preserves every unrelated setting, keeps a hash-checked backup, and restarts a supervised gateway only when one was already running. |
| OpenClaw | Creates an isolated Omnious profile with auto selected, an authenticated setup-time snapshot of every available model, and a read-only RFQ observer plugin with prompt and conversation access disabled. The plugin also adds /omnious-rfq. | The ordinary OpenClaw profile remains untouched. |
| Claude Code | Creates a dedicated config home, credential helper, launcher, and read-only auction status display. | Global Claude settings remain untouched; installer-owned profiles can upgrade in place. |
| Codex | Creates an isolated Codex home and named Omnious profile with a display-only Stop hook that renders the cleared RFQ tape after every turn. Codex asks once to trust the hook; its output never enters model context. | The OpenAI default and ordinary Codex home remain untouched. |
| OpenCode | Creates a custom provider overlay using OpenCode's supported OpenAI-compatible package, selects omnious/auto, and lists a read-only RFQ status plugin that toasts the opening market and the cleared tape around each Omnious-served turn. | The global OpenCode config remains untouched. The local overlay works before the reviewed models.dev listing lands and composes with catalog discovery afterward. |
| pi | Creates a profile-local native provider extension with live /models discovery and a read-only RFQ footer backed by /auctions/latest. | The ordinary pi config directory and installed packages remain untouched. |
| OMP | Creates a profile-local models.yml recipe using OMP's native proxy discovery, plus a status-only extension with the same read-only RFQ lifecycle as pi. | PI_CODING_AGENT_DIR isolates its config, auth store, and extensions from the ordinary OMP profile. |
A missing harness CLI no longer stops setup: the installer says exactly what it will run, asks first, and installs the harness before any wallet approval — npm for Claude Code, Codex, OpenCode, pi, and OMP, and Nous Research's official installer for Hermes. Pass --install-harness to skip the prompt in non-interactive runs. OpenClaw installs from npm too and needs Node 22.22.3 or newer — on an older Node the setup still completes, skips the launch, and says exactly how to upgrade and re-run.
Rerunning the same one-line command always converges: an existing installer-owned profile that is untouched is upgraded in place with its credential reused (no second wallet approval), one that routes to a different deployment is replaced cleanly with a fresh approval, and only files the installer does not recognize as its own — or that were edited after installation — stop it, so your changes are never overwritten silently.
Safety contracts
- Bounded before issuance. The wallet signature binds the harness, deployment, label, budget, reset window, and session expiry.
- One-time delivery. A device code can exchange an approved session once; replay and expired sessions cannot mint a key.
- No paid fallback. Isolated profiles route to Omnious only, so a failed market request cannot silently spend through another provider.
- Reversible local writes. The CLI records the files and hashes it owns. Rollback preserves anything edited after installation instead of overwriting it.
- Auditable verification. Every paid compatibility probe prints its request ID, which resolves to the same receipts and analytics as ordinary traffic.
Compatibility verification
Unless explicitly skipped, every harness runs the same bounded suite: credential isolation, OpenAI error shape, model discovery, ordinary chat, SSE streaming, a forced function call, and tool-result continuation. Four checks are real paid requests, capped at 128 output tokens in total; the other three are rejected boundary checks or metadata reads and cost nothing.
The app shows what the selected installer writes and the CLI prints the exact launch, verification, and rollback instructions after a successful exchange. Once verification passes, it opens the selected harness in that isolated profile; a failed compatibility check leaves the profile installed but does not open it. Keeping those operational commands in Integrations prevents a stale docs snippet from becoming a second setup path.
Manual clients and RFQ visibility
A custom OpenAI-compatible client can still use the same endpoint and a governed x-credit-key; see API quickstart. Every harness setup now includes a read-only live RFQ view backed by the key-scoped latest-auction endpoint: Claude Code and pi render status displays, Codex prints the cleared tape from its Stop hook, OpenCode toasts it, and OMP shares pi's status lifecycle. Hermes and OpenClaw users can also type /omnious-rfq for the same no-charge, read-only view; the command is handled by the plugin before model invocation, so its result is never prompt context or a fake tool call. Their isolated plugins also emit generic transient status for automatic rendering as soon as the corresponding upstream harness extension ships.
Choose a harness and connect it in Integrations →
- router/cli/setupHarness.ts device flow, local install plans, compatibility checks, and rollback
- router/src/agent/setup.ts short-lived session issuance and one-time key exchange
- frontend/src/components/integrations/HarnessSetup.tsx the canonical approval and setup surface