CLI troubleshooting

Check the failure layer by layer: installation and dependencies, background service, account, provider and route, remote capability, and finally the App. For a first installation, run originrouter setup. In a native-agent workflow, an account failure in doctor is not by itself a blocker; continue with local service and agent checks.

Missing installation prerequisites

The install script requires curl and Node.js 22+ (including npm). On fresh systems, the script installs Node.js automatically: system package managers (apt, dnf/yum, apk via NodeSource 22 LTS) when root or passwordless sudo is available; otherwise it installs nvm and puts Node.js in the user's home directory, requiring no sudo at all.

When automatic installation fails, resolve by cause:

• Insufficient privileges (a message about root privileges): the script falls back to a user-level nvm install automatically; if that also fails, run the install command in a root session, or configure sudo for the current user and retry.
• Network timeouts (curl: (28) Connection timed out): configure a terminal proxy and retry, or install Node.js manually:
  • macOS: brew install node@22, or the official installer from nodejs.org.
  • Debian / Ubuntu: curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash - && sudo apt-get install -y nodejs
  • RHEL / CentOS / Alibaba Cloud Linux: curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash - && sudo dnf install -y nodejs
  • Alpine: apk add --no-cache nodejs npm
  • Other systems: install from nodejs.org.
• Version still reported as outdated after installation: run node --version to confirm, and check for multiple Node installations (for example nvm alongside a system package) leaving an old version first on PATH.

After Node.js is installed, run the install command again.

Agent runtime download failures (special network required)

When installing Claude Code and Codex, originrouter setup downloads them from the official Anthropic and OpenAI sources:

• Claude Code: curl -fsSL https://claude.ai/install.sh | bash
• Codex: curl -fsSL https://chatgpt.com/codex/install.sh | sh

Both domains restrict access from some regions and data-center IP ranges (typically curl: (22) The requested URL returned error: 403). Running setup directly on a cloud server in an unsupported region or on a restricted network can therefore fail for Claude Code or Codex. The Start Codex now? [y/N] prompt during Codex installation comes from the official Codex installer; answer n to skip it — this does not affect the installation.

How to resolve:

• Configure a working proxy for the terminal and run originrouter setup again. Setup is safe to re-run; components that are already installed are skipped.
• Install manually, then run originrouter setup again to finish the remaining steps:
  • Claude Code: npm i --global @anthropic-ai/claude-code, or download from claude.ai/code.
  • Codex: npm i --global @openai/codex, or see developers.openai.com/codex.
• Installed but not recognized: reopen the terminal so PATH takes effect, then run originrouter doctor to check the agent runtimes.

Basic diagnostics

originrouter --version
originrouter doctor
originrouter status
originrouter service status

Run these checks in order: confirm the CLI binary and version, inspect dependencies and providers, inspect installation and device state, then confirm the background service.

If the command is missing, confirm that the npm global bin directory is in PATH and reopen the terminal. Do not mix a global npm i with an old npm link development checkout.

Service not ready

originrouter service restart
originrouter local config show
originrouter daemon-port

Run these checks in order: restart the service, inspect Local API configuration, then read the active Local API port.

Then inspect:

~/.originrouter/logs/daemon.err.log
~/.originrouter/logs/daemon.out.log

Sign-in or account bridge

originrouter auth status
originrouter auth verify
originrouter remote status

Run these checks in order: inspect sign-in state, verify account credentials, then confirm remote connectivity.

On a headless device, run originrouter login --no-browser again. If the device is signed in but not remotely controllable, inspect online state, device trust, and workspace authorization separately.

Providers and routes

originrouter provider list
originrouter route list
originrouter doctor provider <name>
originrouter proxy status
originrouter env print --agent claude

Run these checks in order: list providers, list routes, validate the provider, confirm Proxy state, then inspect Claude's redacted runtime environment.

A provider can exist without an agent slot route. A discovered model can exist without being enabled or selected by a route.

Remote access and workspace

originrouter remote status
originrouter remote share status
originrouter remote workspace list
originrouter devices --json

Run these checks in order: inspect remote connectivity, Remote Share, workspace authorization, and the account device directory.

Protected directories must be reauthorized from the target device's management context. Do not ask a running agent to expand its own directory permission.

Report an issue

Include CLI version, operating system, failing command, redacted error output, and minimal reproduction steps. Remove API keys, tokens, provider credentials, user directories, repository content, and unredacted session text.