Skip to main content
kRouter

CLI reference

Every flag the krouter command accepts, what foreground and tray mode do, exit codes, and how to run kRouter under PM2 or systemd.

npm install -g @sifxprime/krouter installs one command, krouter. It starts the server and the dashboard on port 20128. It needs Node.js 20.9 or newer and refuses to start on anything older.

Basics

# Foreground: start the server, then show a menu in this terminal
krouter
 
# Background: start the server with a tray icon; you can close the terminal
krouter -t

The foreground menu offers Web UI (opens the dashboard in your browser), Terminal UI (an interactive CLI, including settings), Hide to Tray + Start on Login and Exit. Hide to Tray + Start on Login also registers kRouter to start when you log in; it says so and tells you how to undo it. When a newer version is on npm, the menu also shows an Update entry, which stops kRouter and prints the install command to run.

To stop kRouter, press Ctrl-C or choose Exit in the foreground, or right-click the tray icon and choose Quit. Starting krouter again also stops a kRouter that is already running before the new one starts.

All flags

FlagWhat it does
-p, --port PORTPort to listen on. Default 20128. Must be a whole number from 1 to 65535.
-H, --host HOSTAddress to bind. Default 0.0.0.0, reachable from your network. Use 127.0.0.1 to keep it on this machine.
-t, --trayRun in the background with a system tray icon instead of the terminal menu.
-l, --logPrint the server log in this terminal. Without it the log is hidden.
--skip-updateSkip the check for a newer version on npm at start.
-v, --versionPrint the installed version and exit.
-h, --helpPrint usage and exit.

Both --port 3000 and --port=3000 work. An unknown option, or a missing or invalid --port or --host value, prints an error and exits instead of quietly starting on a default. --no-browser (-n) is still accepted so old scripts keep working, but it does nothing: kRouter never opens a browser by itself.

The krouter command ignores the PORT and HOSTNAME environment variables. Use --port and --host. Those variables only apply to the Docker image and to source installs (see Deployment).

When the port is taken

Before it starts, kRouter stops any kRouter that is already running. If another program holds the port, kRouter names it, refuses to kill it, suggests the next port (for example --port 20129) and exits.

Exit codes

CodeMeaning
0Normal exit: --help, --version, Ctrl-C, Exit or Quit
1kRouter could not start or stopped on an error: Node.js older than 20.9, another program holds the port, or the bundled server is missing
2Bad command line: an unknown option, or a missing or invalid --port or --host value

If the server process crashes after starting, the CLI prints the last lines of its error output and restarts it, after a short delay. If it keeps crashing within 30 seconds of each start, the third restart also turns MITM mode off, so a broken MITM setup cannot keep the server down. If the crash says the port is in use, the CLI tries to free it and exits with code 1 when it cannot.

Lost password

Run krouter, choose Terminal UI, then Settings → Reset Password to Default. Then log in with INITIAL_PASSWORD if kRouter was started with one, or else with 123456 from this machine. In Docker (image 0.5.162 or newer): docker exec krouter node scripts/reset-password.js.

Common workflows

Run on another port

krouter -p 28128
# Dashboard: http://localhost:28128/dashboard

Tools you already set up still point at :20128. Change their base URL too, or apply them again from the dashboard's CLI Tools page.

Upgrade

# Quit the running kRouter first (tray icon → Quit, or Ctrl-C)
npm install -g @sifxprime/krouter@latest
 
# Start in the foreground so you can watch it come up
krouter

Run on a server with PM2

On a server without a desktop, use a process manager and pass --skip-update. With that flag and no terminal attached, kRouter runs in background mode instead of waiting for its terminal menu.

npm install -g @sifxprime/krouter pm2
pm2 start krouter --name krouter -- --skip-update
pm2 save && pm2 startup

Add --host 127.0.0.1 after --skip-update when only this machine, or a reverse proxy on it, should reach kRouter. For the first remote login you also need INITIAL_PASSWORD; see Deployment.

Run on a server with systemd

sudo tee /etc/systemd/system/krouter.service << 'UNIT'
[Unit]
Description=kRouter
After=network.target
 
[Service]
Type=simple
User=youruser
ExecStart=/usr/local/bin/krouter --skip-update --port 20128 --host 0.0.0.0
Restart=on-failure
 
[Install]
WantedBy=multi-user.target
UNIT
 
sudo systemctl daemon-reload
sudo systemctl enable --now krouter

Replace youruser with the account that runs kRouter, and /usr/local/bin/krouter with the path which krouter prints for that account. The krouter command starts with #!/usr/bin/env node, so if Node came from nvm, also add an Environment=PATH=... line that includes Node's directory. Data goes to that user's ~/.krouter unless you add Environment=DATA_DIR=....

See the server log

krouter -l prints the server log in the terminal. In tray mode the log is not written to a file, so to watch a problem happen, quit the tray instance and run krouter -l in the foreground. The dashboard's Console Log page also streams the server's console output live.

Where to go next