Install 9Router with npm or Docker

Install the npm package for a local desktop setup, or use the upstream Docker image when you want a container with an explicit data mount. Both expose the local dashboard on port 20128. Start with one provider and one model before adding clients or fallback rules.

9Router is the routing software. A model provider may still require an account, an API balance, or a subscription. Installing the package does not grant model access.

Choose an installation method

Method	Use it when	What you maintain
npm	You already use Node.js and want to run the router on your computer	Node.js, the package version, and the local data folder
Docker	You already run containers or want an explicit deployment definition	The image version, container settings, volume, and host security

These commands are for a shell on macOS or Linux. Windows users can follow the npm route in their normal terminal; Docker requires a working Docker installation. Avoid mixing a Windows client with a WSL server until you have verified how the client reaches that server.

Install with npm

Check your runtime before installing:

node --version
npm --version

Use a currently supported Node.js release. The upstream installation guide recommends Node.js 20 or newer, while the CLI package declares a lower minimum. Using a supported current runtime avoids treating that lower package minimum as a recommendation.

Install the official package and start it:

npm install -g 9router
9router

The dashboard should become available at http://localhost:20128. If your browser does not open it automatically, enter that address yourself. A shell that cannot find 9router after installation usually needs its npm binary path corrected or a new terminal session.

For a project-local installation:

mkdir my-9router
cd my-9router
npm install 9router
npx 9router

Keep the lockfile if you want to record the installed package version. Do not install a similarly named package from an unrelated publisher to solve a download failure. Check the repository link on the npm page against decolua/9router.

Install with Docker

The official image is decolua/9router. This example binds the published port to the host’s loopback interface, so it is intended for clients on that host:

docker run -d \
  --name 9router \
  -p 127.0.0.1:20128:20128 \
  -v "$HOME/.9router:/app/data" \
  -e DATA_DIR=/app/data \
  decolua/9router:latest

The volume and DATA_DIR belong together. The upstream Docker guide places the SQLite database at /app/data/db/data.sqlite with this configuration. On the host, that maps into $HOME/.9router.

Do not run an npm instance and a container against the same live database. If a router already uses that directory, stop it and back up the data before moving between installation methods. For a fresh test, use a separate host folder.

Inspect startup output:

docker logs --tail 100 9router

A container that keeps restarting has not passed installation. Read the first relevant error, check port conflicts and volume permissions, and fix that condition before configuring a client.

latest follows upstream releases. Once you choose a working release, record the image tag or digest. Check the published registry before pinning a version; a GitHub release name alone does not prove the corresponding container tag exists.

Verify the server

Test the local health endpoint:

curl -i http://localhost:20128/api/health

A successful HTTP response confirms that the server answers that request. It does not confirm authentication, provider quota, model compatibility, or a completed inference.

Next, open the dashboard and connect a provider you already have access to. For an API-key connection, the upstream quickstart uses Providers, then Add API Key: select the provider, enter its key, and save. For a supported subscription connection, choose Connect for that provider and follow its sign-in flow. Labels can differ by release; check your installed dashboard. Keep provider credentials in your own instance. Create or copy a router API key from the dashboard when API authentication is enabled; do not confuse this with the dashboard login password.

Use the dashboard’s endpoint instructions to inspect the model list. A shell example, after you set NINE_ROUTER_KEY locally, is:

curl --fail-with-body http://localhost:20128/v1/models \
  -H "Authorization: Bearer $NINE_ROUTER_KEY"

Copy an exact model ID from the response or dashboard. Finally, send a short, non-sensitive prompt through your chosen client and inspect the corresponding request in the router. This final step may consume provider quota. A model appearing in a list is not proof that your account can use it.

Understand where localhost points

localhost means the machine or container making the request. A client running on another laptop cannot reach your router using its own localhost. A client in another container needs an appropriate container network address.

Keep the first setup local. If you later expose the router remotely, configure HTTPS, access controls, and a deliberate network boundary before changing client URLs. Publishing a dashboard is a separate deployment task; it is not required to follow this Wiki.

Update without losing your setup

Record the working version and back up the data while the router is stopped. For npm, use npm list -g 9router --depth=0 to identify the global package, or npm list 9router --depth=0 inside a local installation.

For Docker, stop the container before copying its data. Update the image, recreate the container with the same intended volume, then repeat the health and client checks. Preserve the previous image reference and backup until the new version works. A database migration may mean that reverting the image alone is insufficient.

When the endpoint works, continue with Claude Code, Codex, or OpenCode. If it does not answer, use the troubleshooting sequence before adding more components.

Why does the Docker initial password not work?

First determine whether the container is using a fresh or existing data volume. Initialization settings can differ from credentials already persisted in a database. Upstream issue #5113 reports a Docker password problem, but the report alone does not establish a confirmed reset procedure.

Record the image tag, inspect the startup log, and check how the environment variable reaches the container. Back up the data before following the version-specific recovery instructions. Do not delete a populated volume merely to force an initial password: it may contain your provider connections and settings. If you are using the published CLI instead, use the dedicated npm installation and error guide.