npm install 9Router: setup and error fixes

To install the published 9Router CLI, check your Node.js environment, run npm install -g 9router, then start 9router. The install command downloads the application; you still need to start it and configure a provider before a coding client can make useful model requests.

This page focuses on the npm workflow. For Docker, data persistence, and the broader setup sequence, use Install 9Router.

1. Check the runtime and package

node --version
npm --version
npm view 9router version engines repository.url

The upstream README documents Node.js 20 or later. Check the package’s current engine requirements too; package releases can change independently of a tutorial. If Node or npm is missing, install an appropriate Node version through your normal runtime manager or the official distribution, then open a fresh terminal.

Confirm that the package points to the intended 9Router project. This metadata check does not run the package or authenticate to a model provider.

2. Install and start

npm install -g 9router
npm list -g 9router --depth=0
9router

Keep the startup output visible. Open the local dashboard address printed by your instance; the documented default port is 20128. If the process exits immediately, diagnose that first rather than configuring several coding clients against a server that is not running.

A successful install does not imply a background service was created. Unless you have deliberately configured a service manager, closing the process can stop the server. Verify how your installation is being started before relying on it for a long-running agent.

3. Connect a provider and check the API

Follow the dashboard’s provider setup for the account or API credential you intend to use. Create or use the router API key required by your instance. Then check:

curl -i http://localhost:20128/api/health
curl -i http://localhost:20128/v1/models \
  -H "Authorization: Bearer $NINEROUTER_API_KEY"

Set the environment variable to your router-issued key. Choose a model ID from the returned catalog and test a small request. The health endpoint verifies reachability, and the model list verifies discovery; provider inference remains a separate check.

Common npm install failures

Symptom	Check first	Practical next step
npm: command not found	Node installation and terminal environment	Install or select the intended Node runtime
9router: command not found	Global prefix and shell PATH	Locate the executable and reopen the shell if needed
EACCES	Ownership of the global installation directory	Follow npm’s version-manager or writable-prefix guidance
Registry timeout or DNS error	Registry reachability from this shell	Check network and configured registry before retrying
Unsupported engine	Installed Node versus package requirements	Select a compatible runtime
Address already in use	Another process listening on the chosen port	Reuse the intended instance or configure a separate port

Do not delete an existing process or data directory without identifying it. Two terminals can start competing copies of the router, and installing a new package does not stop the old process automatically.

Update without losing the baseline

Record the installed package version and back up the router’s persistent data according to its documented location. Update only after reading the relevant release changes:

npm install -g 9router@latest
npm list -g 9router --depth=0

Restart the intended process and repeat the same endpoint checks. If you need to investigate a regression, record both versions and the exact failure. Do not assume a downgrade is compatible with data already migrated by a newer version.

What does a bare npm install do?

Inside a source checkout, npm install installs that application’s dependencies. It is not shorthand for installing 9Router globally. Source builds have their own environment, build, and startup instructions. See the GitHub guide before switching paths, and keep the two installations distinguishable while debugging.