omnious

The command-line front door to Omnious: an RFQ market for LLM inference. Each request opens an auction, providers bid to serve it, the router clears the market, and the winning response streams back with a receipt.

Use the CLI directly, or connect an existing agent harness:

• Claude Code — isolated settings, live Omnious status and auction clears
• Codex — isolated Responses API profile
• OpenClaw — isolated state directory and Responses API provider
• Hermes — isolated profile, or install Omnious as the active model endpoint
• Any OpenAI-compatible client — one base URL, one bounded credit key

Runs on Node 18+ or Bun. No source checkout is required.

Install or run once

# Run the latest release without installing it
npx --yes omnious@latest

# Or install it globally
npm install --global omnious@latest
omnious

# Bun equivalents
bunx omnious@latest
bun add --global omnious@latest

Check exactly which version you are running:

npx --yes omnious@latest --version
omnious --version

Bare omnious opens the full-screen market terminal. Harness setup works from any directory; do not cd into the Omnious repository first.

Choose a harness

| Harness | Setup command | Opt-in launcher | | --- | --- | --- | | Claude Code | setup claude-code | claude-omnious-mainnet | | Codex | setup codex | codex-omnious-mainnet | | OpenClaw | setup openclaw | openclaw-omnious-mainnet | | Hermes, isolated | setup hermes | hermes-omnious-mainnet | | Hermes, active profile | hermes | installs the model endpoint and opens Hermes |

Every setup command:

1. creates a one-time device session;
2. opens a browser page showing the exact label, network, budget and reset window;
3. asks for one gasless wallet signature;
4. receives a bounded spend key only after approval;
5. writes a protected, reversible local profile;
6. verifies authentication, models, chat, streaming and tool calls; then
7. opens the harness with the new Omnious profile already active.

The ordinary configuration for Claude Code, Codex and OpenClaw is not changed. Their Omnious launchers opt into separate profiles. The Hermes shortcut updates only the active profile's model endpoint and makes a hash-checked backup; it does not assume Telegram, Discord, or any other channel. Automatic launch happens only after verification passes; use --no-launch for scripts or headless setup.

Claude Code

Install a mainnet profile with a maximum spend of $100 per day:

npx --yes omnious@latest setup claude-code \
  --router https://api.omnious.xyz \
  --environment mainnet \
  --label claude-code-mainnet \
  --budget 100 \
  --budget-window daily

Setup opens Claude through the isolated profile automatically. To relaunch it later:

claude-omnious-mainnet

# If ~/.local/bin is not on PATH:
~/.local/bin/claude-omnious-mainnet

The launcher uses:

• ~/.claude/profiles/omnious-mainnet/settings.json
• model auto, auction-routed by Omnious
• an isolated credential helper
• the Omnious Anthropic-compatible endpoint
• Claude's normal local tools, including Agent and Skill

Claude displays Omnious inside its own interface:

◇ OMNIOUS · MAINNET · AUTO · LIVE RFQ
◇ opening market · solicit → score → clear → serve

AUTO is the default, not a hard-coded routing claim. The label follows the active Claude model after a pinned launch or an in-session switch. Run /model to choose from the quoted Omnious classes returned by Claude's last successful gateway refresh, or switch directly with a class id such as /model glm-5.2 or /model kimi-k3. A switch is checked against the current quote book; Claude's validation probe is answered locally and does not open a paid auction.

To update an existing Omnious Claude profile, re-run the same setup command. An installer-owned profile with no edits beyond its saved model is upgraded in place before any wallet flow, keeping its spend key and model selection.

After the response, the display updates to the real key-scoped clear: quote count, winning model, price setter and charge. Identity, live state, pending steps and cleared tape use distinct ANSI colours. Set NO_COLOR=1 to disable colour.

The display is read-only. It reads /v1/auctions/latest, emits only visible status output, and never changes Claude's prompt, context, tools or answer. Plan mode, Agent subagents and bundled skills continue through the same Omnious profile.

Rollback:

npx --yes omnious@latest setup claude-code \
  --environment mainnet \
  --uninstall

Codex

Install an isolated Codex profile:

npx --yes omnious@latest setup codex \
  --router https://api.omnious.xyz \
  --environment mainnet \
  --label codex-mainnet \
  --budget 100 \
  --budget-window daily

Launch it:

codex-omnious-mainnet

# Or use the absolute launcher path:
~/.local/bin/codex-omnious-mainnet

The installer writes an isolated config at:

~/.codex/profiles/omnious-mainnet/omnious-mainnet.config.toml

That profile selects model auto, uses the OpenAI Responses wire API at https://api.omnious.xyz/v1, and exports the bounded key only inside the launcher process. Your ordinary ~/.codex/config.toml stays unchanged. Codex tools remain local; model requests route through the Omnious auction.

Rollback:

npx --yes omnious@latest setup codex \
  --environment mainnet \
  --uninstall

OpenClaw

Install an isolated OpenClaw state directory:

npx --yes omnious@latest setup openclaw \
  --router https://api.omnious.xyz \
  --environment mainnet \
  --label openclaw-mainnet \
  --budget 100 \
  --budget-window daily

Launch it:

openclaw-omnious-mainnet

# Or:
~/.local/bin/openclaw-omnious-mainnet

The installer creates:

~/.openclaw-omnious-mainnet/openclaw.json
~/.openclaw-omnious-mainnet/.env
~/.local/bin/openclaw-omnious-mainnet

The isolated profile uses model auto, the Responses API, Omnious pricing and no paid fallback provider. Running ordinary openclaw still uses your existing configuration.

Rollback:

npx --yes omnious@latest setup openclaw \
  --environment mainnet \
  --uninstall

Hermes: install a model endpoint

To make Omnious the model endpoint for whichever Hermes profile is active, run:

npx --yes omnious@latest hermes

Omnious checks hermes config path before creating a wallet approval session or opening the browser. If Hermes is already installed at ~/.local/bin/hermes but the current shell has not reloaded, the command uses that launcher directly. On macOS, Linux, and WSL, if Hermes is missing, an interactive run asks before downloading and running Nous Research's official per-user installer and its managed dependencies from hermes-agent.nousresearch.com. It passes --skip-setup so Hermes' provider wizard does not compete with this integration, verifies hermes version, and only then proceeds to wallet approval. For a non-interactive shell, pass --install-hermes to give that installation consent up front. A declined or failed install still requests no wallet approval. Native Windows keeps the preflight-only behavior and points to the official Windows installer.

The shortcut means:

npx --yes omnious@latest setup hermes \
  --active-profile \
  --router https://api.omnious.xyz \
  --environment mainnet \
  --label hermes-mainnet \
  --budget 100 \
  --budget-window daily

It asks Hermes for the active config.yaml and .env paths, preserves every non-model and channel setting, and changes only the model provider:

model.default  = auto
model.provider = custom
model.base_url = https://api.omnious.xyz/v1
model.api_mode = chat_completions

The endpoint install does not require a chat channel or start a gateway. If a supervised Hermes gateway is already running, setup restarts it so the active service picks up the endpoint. If Hermes reports an unsupervised manual gateway, setup stops before changing files; either stop that process or install the supervised service first:

hermes gateway install
npx --yes omnious@latest hermes

Rollback restores the exact backup and restarts the supervised gateway:

npx --yes omnious@latest hermes \
  --environment mainnet \
  --uninstall

If either Hermes file changed after setup, rollback preserves the newer edit and stops for manual review instead of overwriting it.

Hermes: keep the existing profile untouched

To create a separate opt-in Hermes profile instead:

npx --yes omnious@latest setup hermes \
  --router https://api.omnious.xyz \
  --environment mainnet \
  --label hermes-isolated-mainnet \
  --budget 100 \
  --budget-window daily

hermes-omnious-mainnet

The isolated files live under:

~/.hermes/profiles/omnious-mainnet/

Rollback:

npx --yes omnious@latest setup hermes \
  --environment mainnet \
  --uninstall

Budgets and environments

The default setup budget is $100 per day. Override it explicitly:

# $25 per day
--budget 25 --budget-window daily

# $250 per week
--budget 250 --budget-window weekly

# $500 per month
--budget 500 --budget-window monthly

Supported reset windows are daily, weekly and monthly. Supported environments are mainnet and testnet; the selected environment must match the router URL reported by the approval page.

The wallet approves the limit before the spend key exists. The device code is single-use, the key is stored with mode 0600, and setup never prints the key.

Useful setup flags:

--router <url>              router base URL
--environment <name>       mainnet or testnet
--label <name>             wallet-visible key label
--budget <usd>             maximum spend for the reset window
--budget-window <window>   daily, weekly or monthly
--install-hermes           install missing Hermes before wallet approval
--no-open                  print the approval URL instead of opening it
--no-verify                install without paid compatibility probes
--no-launch                install without opening the harness afterward
--uninstall                remove or restore the selected setup

--active-profile and --install-hermes are supported only for the active Hermes model endpoint.

What verification tests

Unless you pass --no-verify, every harness runs the same seven checks:

1. credential isolation;
2. OpenAI-compatible validation errors;
3. model discovery;
4. ordinary chat;
5. SSE streaming;
6. a forced tool call; and
7. continuation after the tool result.

The CLI prints PASS or FAIL, details and paid request IDs. Four checks are real paid requests, capped together at 128 output tokens. No fallback provider is used. If verification cannot start, the isolated profile remains installed and the CLI says so plainly without opening the harness.

Upgrade or reinstall

npx --yes omnious@latest ... always uses the newest package. Upgrade a global installation with:

npm install --global omnious@latest
omnious --version

Installer-managed profiles are intentionally not overwritten in place. To regenerate one with a newer CLI, uninstall that isolated profile and run setup again:

npx --yes omnious@latest setup claude-code --environment mainnet --uninstall
npx --yes omnious@latest setup claude-code \
  --router https://api.omnious.xyz \
  --environment mainnet \
  --label claude-code-mainnet \
  --budget 100 \
  --budget-window daily

Each setup has a hash-checked manifest under ~/.omnious/setups/. Uninstall removes only files whose contents still match what the installer wrote. Files you edited later are preserved for review.

Troubleshooting

command not found: claude-omnious-mainnet

Use the absolute launcher path:

~/.local/bin/claude-omnious-mainnet

Or add the launcher directory to zsh once:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

The same applies to the Codex, OpenClaw and isolated Hermes launchers.

Module not found "cli/omnious.ts"

That command is only for developers already inside the source repository. From any directory, use the published package:

npx --yes omnious@latest setup claude-code --router https://api.omnious.xyz

A copied command split into separate shell commands

Copy a complete code block. In a multiline command, every \ must be the final character on its line. A path must not contain a newline:

npx --yes omnious@latest setup claude-code \
  --router https://api.omnious.xyz \
  --environment mainnet

The approval browser did not open

Print the URL and open it yourself:

npx --yes omnious@latest setup codex \
  --router https://api.omnious.xyz \
  --environment mainnet \
  --no-open

Confirm that the code, harness, environment, label and budget shown in the browser exactly match the terminal before signing.

isolated setup already exists

The installer will not overwrite an existing profile. Uninstall the named harness first, review any preserved modified files, then run setup again.

Hermes endpoint setup refuses a running gateway

The gateway is running outside Hermes supervision. Setup stops before changing configuration. Run:

hermes gateway install
npx --yes omnious@latest hermes

Inspect the active CLI configuration

omnious inspect
omnious health
omnious models

Use the market directly

Bare omnious opens the interactive market terminal. Arrow keys navigate, / filters, Enter opens an ask ladder, a asks the selected model, y copies the reply and ? shows every key.

The same surfaces are available as one-shot commands:

# Replay setup and connectivity
omnious welcome

# Pay and stream a completion
omnious ask "Explain why request auctions lower inference cost."

# Choose routing behaviour or pin a model class
omnious ask "Use the cheapest suitable route." --priority cheapest
omnious ask "Prove this carefully." --reasoning-effort high
omnious ask "Use this class." --model <model-class>

# Run an interactive conversation
omnious chat

# Watch the live market
omnious models
omnious book --watch
omnious stats --json

# Inspect a completed request
omnious receipt <request-id>
omnious economics <request-id>

# Full command reference
omnious help

Useful inference controls:

--profile balanced|frontier|speed|value|reasoning|coding
--priority cheapest|fastest|balanced
--reasoning-effort none|low|medium|high|max
--max-price <usd>
--max-spend <usd>
--session-budget <usd>
--tools
--web
--agents
--computer
--output-format json|stream-json

Paid local loops have a cumulative $1 default cap. Set --max-spend to an explicit positive USD amount, or use --allow-unbounded-spend only when you deliberately want no cumulative CLI cap.

Wallets

The recommended local wallet is encrypted with scrypt and AES-256-GCM:

omnious wallet create
omnious wallet import
omnious wallet list
omnious wallet use <name>
omnious wallet remove <name>

Paid commands unlock the active wallet with its password. For automation, OMNIOUS_WALLET_PASSWORD unlocks the keystore non-interactively, while OMNIOUS_WALLET_KEY=0x... overrides it with an environment key.

Harnesses normally use the bounded prepaid credit key created by setup, so they do not perform a wallet signature on every inference request.

Connect any OpenAI-compatible client

The harness installer is convenient, but the wire configuration is small:

base URL   https://api.omnious.xyz/v1
model      auto
header     x-credit-key: <bounded spend key>

Use a model class instead of auto only when you intentionally want to pin routing. Create and govern bounded keys through the Omnious spend-governance interface.

From source

Only repository contributors need this:

git clone https://github.com/synx-storage/omnious-master.git
cd omnious-master/router
bun install --frozen-lockfile
bun cli/omnious.ts help

Links

• Product: https://omnious.xyz
• Documentation: https://docs.omnious.xyz
• Harness guide: https://docs.omnious.xyz/customers/harnesses
• Source: https://github.com/synx-storage/omnious-master
• Issues: https://github.com/synx-storage/omnious-master/issues