Prerequisites

  • Node.js >= 20.0.0 (installed automatically by the installer if not present)
  • npm or yarn

The recommended way to install sshift - automatically handles updates and autostart configuration:

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/lethevimlet/sshift/main/sshift-install.sh | bash

Or with wget:

wget -qO- https://raw.githubusercontent.com/lethevimlet/sshift/main/sshift-install.sh | bash

Windows PowerShell (Admin)

Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/lethevimlet/sshift/main/sshift-install.ps1" -UseBasicParsing).Content

What the Installer Does

  1. Checks for Node.js - Installs Node.js 20+ if not present
  2. Installs via npm - Installs sshift globally using npm
  3. Creates configuration - Sets up config at ~/.local/share/sshift/.env/config.json with HTTPS enabled
  4. Configures autostart (optional) - Sets up sshift to start on boot
  5. Starts the service - Automatically starts sshift after installation
  6. Checks for updates - Compares local and remote versions

Custom Installation Options

You can customize the installation with command-line arguments:

Linux / macOS

# Install with custom port
curl -fsSL https://raw.githubusercontent.com/lethevimlet/sshift/main/sshift-install.sh | bash -s -- --port 8080

# Show help
./sshift-install.sh --help

Windows PowerShell (Admin)

# Install with custom port
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/lethevimlet/sshift/main/sshift-install.ps1" -OutFile "sshift-install.ps1"
.\sshift-install.ps1 -port 8080

# Show help
.\sshift-install.ps1 -help

Docker

Run sshift using Docker:

docker run -d -p 8022:8022 --name sshift ghcr.io/lethevimlet/sshift:latest

Or with docker-compose:

curl -O https://raw.githubusercontent.com/lethevimlet/sshift/main/docker/docker-compose.yml
docker-compose up -d

See Docker documentation for detailed instructions.

npm Installation

Install globally via npm:

# Install globally
npm install -g @lethevimlet/sshift

# Start the server
sshift

The application will be available at https://localhost:8022

Updating

npm update -g @lethevimlet/sshift

Uninstallation

npm uninstall -g @lethevimlet/sshift

Manual Installation from Source

If you prefer to install from source:

# Clone the repository
git clone https://github.com/lethevimlet/sshift.git
cd sshift

# Install dependencies
npm install

# Start the server
npm start

The application will be available at https://localhost:8022 (default production port)

CLI Reference

sshift                      Start server on default port (8022)
sshift --dev                Start in development mode (port 3000, separate PID)
sshift --port 8080          Start server on custom port
sshift --bind 127.0.0.1     Bind to specific address
sshift --status             Check if sshift is running
sshift --stop               Stop running instance
sshift --restart            Restart running instance
sshift --dev --status       Check if dev instance is running
sshift --dev --stop         Stop dev instance
sshift --dev --restart      Restart dev instance
sshift --help               Show help message
Flag Shorthand Description
--port <port> -p Server port (default: 8022, dev: 3000)
--bind <addr> -b Bind address (default: 0.0.0.0)
--dev -d Development mode — uses devPort from config (default 3000) and a separate PID file so dev and production instances can run side-by-side
--stop -s Stop running instance
--restart -r Restart running instance
--status   Check running status
--help -h Show help message

Development Mode (--dev / -d)

The --dev flag starts sshift in development mode:

  • Sets NODE_ENV=development — switches the default port from 8022 to 3000 (or the devPort configured in config.json)
  • Separate PID file — uses .sshift-dev.pid instead of .sshift.pid, so a dev instance and a production instance can run simultaneously
  • Instance management — --dev can be combined with --status, --stop, and --restart to manage the dev instance independently
# Start in development mode
sshift --dev

# Or via npm
npm run dev

# Check dev instance status
sshift --dev --status

# Stop dev instance (production is unaffected)
sshift --dev --stop

# Restart dev instance
sshift --dev --restart

You can also set NODE_ENV=development directly:

NODE_ENV=development sshift

Port Configuration

SSHIFT uses a flexible port configuration system with the following priority (highest to lowest):

  1. --port CLI argument (sets PORT env var; highest priority)
  2. PORT environment variable (from .env files or shell)
  3. config.json devPort (when NODE_ENV=development or --dev)
  4. config.json port (production)
  5. Default ports: 8022 (production), 3000 (development)
# Run on custom port (CLI argument)
sshift --port 9000

# Run on custom port (environment variable)
PORT=9000 ./sshift

# Run in development mode (uses devPort from config or 3000)
sshift --dev

# Or configure in config.json
{
  "port": 8022,      # Production port
  "devPort": 3000    # Development port
}

Bind Address Configuration

SSHIFT can bind to a specific network interface. By default, it binds to 0.0.0.0 (all interfaces).

  1. --bind CLI argument (sets BIND env var; highest priority)
  2. BIND environment variable (from .env files or shell)
  3. config.json bind setting
  4. Default: 0.0.0.0 (all interfaces)
# Bind to localhost only (CLI argument)
sshift --bind 127.0.0.1

# Bind to localhost only (environment variable)
BIND=127.0.0.1 ./sshift

# Bind to specific interface
sshift --bind 192.168.1.100

# Or configure in config.json
{
  "bind": "0.0.0.0"  # Bind to all interfaces (default)
}

Trusting the HTTPS Certificate

SSHIFT signs its HTTPS certificate with its own local certificate authority (CA), created on first start and kept in ~/.local/share/sshift/ so it survives updates. For service workers (which enable offline caching) to function, your browser must trust that CA. Follow the instructions for your platform below — you only do this once per device; certificates re-issued later (new IP, renewal) are trusted automatically.

First, download the CA certificate by clicking Download CA Certificate in the Security & Connection Info dialog, or navigate to https://<your-host>:8022/api/cert in your browser. The same URL works over plain http:// for devices that do not trust the CA yet.

Chrome / Edge (Desktop)

  1. Open chrome://settings/certificates (or edge://settings/certificates) in the address bar
  2. Click Import and select the downloaded .crt file
  3. Choose Trusted Root Certification Authorities as the store
  4. Restart the browser and reload sshift

Chrome / Brave (Android)

  1. Open https://<your-host>:8022/api/cert in the browser (or use the download button); sshift-ca.crt lands in Downloads
  2. Go to Settings > Security & privacy > More security settings > Encryption & credentials > Install a certificate > CA certificate
  3. Confirm the warning and select the downloaded sshift-ca.crt
  4. Restart the browser and reload sshift

The file must be a CA certificate (CA:TRUE) for Android to accept it; sshift versions before 1.8.1 served a plain self-signed certificate that Android rejected.

Firefox

  1. Open about:preferences#privacy
  2. Scroll to Certificates and click View Certificates
  3. Click Import and select the .crt file
  4. Check Trust this CA to identify websites
  5. Restart the browser and reload sshift

macOS

  1. Double-click the downloaded .crt file
  2. When prompted, add it to the System keychain
  3. Open Keychain Access, find the certificate, and double-click it
  4. Expand Trust and set When using this certificate to Always Trust
  5. Close the dialog and authenticate to save changes
  6. Restart the browser and reload sshift

iOS

  1. Open the downloaded .crt file on your device
  2. Go to Settings > General > VPN & Device Management and install the profile
  3. Go to Settings > General > About > Certificate Trust Settings
  4. Enable full trust for the certificate
  5. Restart the browser and reload sshift

Linux (system-wide)

On most Linux distributions you can trust the certificate system-wide:

# Debian/Ubuntu
sudo cp sshift.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

# RHEL/CentOS/Fedora
sudo cp sshift.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust

Note that system-wide trust does not affect Chromium-based browsers, which use their own certificate store. Follow the Chrome/Edge instructions above for those browsers.