Skip to main content
kRouter

Deployment

Run kRouter on a VPS, in Docker, behind PM2, or as a cloud worker. Production-ready configurations and environment variables.

kRouter ships with three deployment paths. Pick the one that matches your infrastructure.

VPS deployment

The cheapest production setup: a $5/month VPS with Node 20+.

# Pull and install
git clone https://github.com/sifxprime/krouter.git
cd krouter
npm install
npm run build:deploy
 
# Set production env vars
export JWT_SECRET="generate-a-long-random-string"
export INITIAL_PASSWORD="your-first-login-password"
export DATA_DIR="/var/lib/krouter"
export PORT="20128"
export HOSTNAME="0.0.0.0"
export NODE_ENV="production"
export AUTH_COOKIE_SECURE="true"   # required behind HTTPS
 
# Start
npm run start

For long-running operation use PM2:

npm install -g pm2
pm2 start npm --name krouter -- start
pm2 save
pm2 startup            # auto-restart on reboot

Docker

The official image is published to Docker Hub and GitHub Container Registry, multi-arch (linux/amd64 + linux/arm64).

docker run -d \
  --name krouter \
  -p 20128:20128 \
  -v "$HOME/.krouter:/app/data" \
  -e DATA_DIR=/app/data \
  -e JWT_SECRET="..." \
  -e INITIAL_PASSWORD="..." \
  sifxprime/krouter:latest

The bind mount keeps your SQLite database and OAuth refresh tokens on the host so container restarts don't lose state.

Cloudflare Workers

For global edge deployment with no servers to manage. kRouter compiles to a Worker bundle, with state stored in D1 (Cloudflare's SQLite).

This is an advanced path — see the Cloudflare deployment guide on GitHub for the wrangler config and D1 migration steps.

Environment variables

VariableDefaultPurpose
JWT_SECRETauto-generated at ~/.krouter/jwt-secretSigns the dashboard auth cookie
INITIAL_PASSWORD123456First-login password when no hash exists
DATA_DIR~/.krouterSQLite + cert + runtime state location
PORTframework defaultHTTP port (use 20128 for consistency)
HOSTNAMEframework defaultBind host (0.0.0.0 for Docker)
NODE_ENVruntime defaultSet production for deploy
AUTH_COOKIE_SECUREfalseSet true behind HTTPS reverse proxy
REQUIRE_API_KEYfalseForce Bearer auth on /v1/* (recommended for public endpoints)
API_KEY_SECRETendpoint-proxy-api-key-secretHMAC secret for generated API keys
BASE_URLhttp://localhost:20128Server-side internal base URL (cloud sync)
HTTP_PROXY / HTTPS_PROXYemptyOptional outbound proxy for upstream calls
ENABLE_REQUEST_LOGSfalseEnable logs/ directory for request traces

Reverse proxy (HTTPS, custom domain)

Most users put kRouter behind Cloudflare Tunnel or Nginx for HTTPS:

server {
  listen 443 ssl;
  server_name router.example.com;
 
  ssl_certificate     /etc/letsencrypt/live/router.example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/router.example.com/privkey.pem;
 
  location / {
    proxy_pass         http://127.0.0.1:20128;
    proxy_set_header   Host $host;
    proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header   X-Forwarded-Proto https;
    proxy_buffering    off;          # critical for SSE streaming
    proxy_read_timeout 600s;
  }
}

Set AUTH_COOKIE_SECURE=true and REQUIRE_API_KEY=true when exposing publicly.

Data persistence

Everything kRouter persists lives under ${DATA_DIR}/:

${DATA_DIR}/
├── db/
│   ├── data.sqlite          # main DB — providers, combos, settings, history
│   └── backups/             # automated backups
├── certs/                   # MITM root CA (only if MITM mode enabled)
└── logs/                    # request logs if ENABLE_REQUEST_LOGS=true

Back up db/data.sqlite for full disaster recovery. Delete ${DATA_DIR} for a clean reset.

Updating in production

# Git clone install
cd krouter
git pull
npm install
npm run build:deploy
pm2 restart krouter
 
# Docker
docker pull sifxprime/krouter:latest
docker rm -f krouter
docker run -d ... sifxprime/krouter:latest

kRouter auto-migrates the SQLite schema on first launch of a new version. No manual migration steps.

Where to go next