npm install 9Router: setup and error fixes

Install the published CLI with npm install -g 9router, then run 9router. If either command fails, use the matching repair below rather than reinstalling blindly. This page handles command lookup, permissions, registry connectivity and occupied ports. Install 9Router owns the npm/Docker choice, persistent data and upgrade procedure.

Start with the package and runtime

node --version
npm --version
npm view 9router version engines repository.url
npm install -g 9router
npm list -g 9router --depth=0
9router

Confirm the metadata points to decolua/9router. The README recommends Node 20 or later; use a supported runtime that also satisfies the current package’s engines. If node or npm itself is missing, install/select Node through your existing runtime manager or Node’s official download instructions, reopen the terminal, and repeat the first two commands.

The default dashboard is http://localhost:20128; prefer the address printed by your process. Installation does not create a running background service. Keep the process terminal open, and use a second terminal for checks.

npm lists 9Router, but the shell cannot find it

On macOS/Linux, inspect the active prefix and executable:

npm prefix -g
command -v node
command -v npm
command -v 9router
ls -l "$(npm prefix -g)/bin/9router"

If that file exists but command -v 9router finds nothing, add its directory to this shell’s search path:

export PATH="$(npm prefix -g)/bin:$PATH"
command -v 9router
9router

Once it works, add the corresponding PATH entry once to your shell’s own startup file, or repair your version manager’s shell initialization. If the file is absent, select the intended Node runtime and reinstall the package under that runtime. A Node version switch can expose a different global package directory.

On Windows PowerShell, global command wrappers live directly under the prefix, not its bin subdirectory:

$npmPrefix = (npm prefix -g).Trim()
Test-Path (Join-Path $npmPrefix '9router.cmd')
Get-Command node, npm, 9router -ErrorAction SilentlyContinue

If the wrapper exists but command lookup fails, test the correction in the current session:

$env:Path = "$npmPrefix;$env:Path"
Get-Command 9router.cmd
9router.cmd

Using the .cmd wrapper also avoids confusing a PowerShell script execution-policy rejection with a missing npm package. After verification, add that directory to your user PATH through Windows Environment Variables and open a fresh terminal. Do not disable the system execution policy just to run an npm wrapper.

EACCES: the global install directory is unwritable

Read the directory named in npm’s error and compare it with npm prefix -g. npm recommends a Node version manager as one remedy. If you already use one, fix/select that user-owned runtime instead of changing ownership of system folders.

For macOS/Linux without a version manager, npm documents moving the global prefix to a user-writable directory. Record the old prefix first; then, if this is the installation layout you want:

npm config get prefix
mkdir -p "$HOME/.local"
npm config set prefix "$HOME/.local"
export PATH="$HOME/.local/bin:$PATH"
npm install -g 9router
npm list -g 9router --depth=0
command -v 9router

Verify the resolved command now comes from the new prefix, then persist that PATH entry once in your shell startup configuration. This prefix change affects future global installs, not just 9Router; record it so you can restore the prior configuration. Do not combine it with a version manager’s incompatible custom-prefix setting. This remedy is not the Windows procedure, and it does not fix an error naming some unrelated protected cache directory. Avoid blanket sudo npm install or recursive ownership changes.

Registry timeout, DNS failure or package not found

Read the first npm error, then inspect this shell’s configured registry:

npm config get registry
npm ping
npm view 9router version repository.url

A successful ping followed by valid package metadata establishes registry access, not package execution. If a company mirror is unreachable or lacks the package, follow that network’s policy. Where direct access to the public npm registry is allowed, test it for this command only:

npm ping --registry=https://registry.npmjs.org
npm view 9router version repository.url --registry=https://registry.npmjs.org

If those succeed and the repository matches, retry the installation with the same command-scoped registry:

npm install -g 9router --registry=https://registry.npmjs.org
npm list -g 9router --depth=0

This leaves your configured registry unchanged. If both routes fail, resolve the reported DNS, proxy, certificate or connectivity problem before retrying. For a managed certificate chain, use your organization’s approved trust configuration; disabling TLS verification is not a repair. Redact credentials embedded in registry/proxy URLs before sharing logs.

EADDRINUSE: port 20128 is occupied

On macOS/Linux with lsof:

lsof -nP -iTCP:20128 -sTCP:LISTEN

On Linux without lsof, use ss -ltnp 'sport = :20128'. On Windows PowerShell:

Get-NetTCPConnection -LocalPort 20128 -State Listen |
  Select-Object LocalAddress, LocalPort, OwningProcess

Replace 1234 below with the observed OwningProcess, not an arbitrary PID:

Get-Process -Id 1234

If the listener is your intended existing 9Router instance, reuse it and open its dashboard. If it is your own disposable test process, stop it from its original terminal with Ctrl+C, rerun the listener check, then start 9router. If it belongs to another service or user, leave it running and consult 9router --help for that installed version’s separate-port setup. Do not kill an unidentified listener.

Verify the repaired server, then connect a provider

In a second terminal on macOS/Linux (use curl.exe in Windows PowerShell):

curl --noproxy '*' -i http://localhost:20128/api/health

A healthy HTTP response confirms the server is reachable. Continue at provider and model verification to configure access and make a small inference request. Keep these outcomes separate: npm installed the package, the process started, the API answered, and the provider completed a request. Only the last tests model access and may consume provider usage.

For version changes and rollback, use the update procedure. A bare npm install inside a repository is a different source-build workflow, explained in npm package and path concepts.