SSHIFT - Web-based SSH/SFTP Terminal Client for the AI Stack

A modern, responsive web-based SSH and SFTP terminal client built with Node.js, Express, and xterm.js. Designed for the AI coding workflow — featuring tab flash notifications that alert you when AI tools like OpenCode or Claude are waiting for your input, so you never miss a prompt while multitasking. Also features excellent TUI support, tabbed sessions, bookmarks, and mobile-friendly design.

📸 Screenshots

✨ Features

• 🔐 SSH Terminal - Full xterm.js emulation with TUI support (vim, nano, htop, tmux)
• 📁 SFTP Browser - File manager interface with upload/download
• 🤖 AI Attention Alerts - Tab flash notifications when AI tools (OpenCode, Claude) need your input
• 🗂️ Tabbed Interface - Multiple concurrent sessions
• 🔖 Bookmarks - Save connection details for quick access
• 🔒 Password Protection - Optional password lock for app access
• ⌨️ Mobile-Friendly - Special keys popup for mobile devices
• 🎨 Modern UI - GitHub-inspired dark theme, fully responsive

🚀 Quick Start

# Install globally
npm install -g @lethevimlet/sshift

# Start the server
sshift

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

📖 Documentation

Full documentation is available at GitHub Pages.

• Installation - Detailed installation options
• Docker - Docker deployment and usage
• Configuration - Configuration files and options
• Plugins - AI attention alerts and plugin system
• API Reference - Socket.IO events and API
• Testing - Running and writing tests
• Contributing - How to contribute

📦 Installation

One-Liner Installation (Recommended)

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

Windows (PowerShell):

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

Note: The Windows installer requires PowerShell to be run as Administrator for npm global installations.

The installer will:

• Install Node.js 20+ if not present
• Install sshift globally via npm
• Start sshift after installation
• Configure autostart (optional, systemd on Linux, launchd on macOS, Task Scheduler on Windows)
• Create config at ~/.local/share/sshift/.env/config.json with HTTPS enabled
• Print summary with HTTPS access links

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 README for detailed instructions.

npm

npm install -g @lethevimlet/sshift
sshift

From Source (GitHub)

git clone https://github.com/lethevimlet/sshift.git
cd sshift
npm install
npm start

⚙️ Configuration

SSHIFT uses a priority-based configuration system. Config files are searched in order; the first match wins.

Config File Search (first match wins)

| Priority | Path | Notes | |----------|------|-------| | 1 | <PACKAGE_DIR>/.env/config.json | NPM package directory | | 2 | <PACKAGE_DIR>/config.json | NPM package root (fallback) | | 3 | ~/.local/share/sshift/.env/config.json | User install location | | 4 | ~/.local/share/sshift/config.json | User install (no .env subdir) |

Port Priority

1. --port CLI argument (highest priority)
2. PORT environment variable
3. config.json devPort (when NODE_ENV=development or --dev)
4. config.json port (production)
5. Default: 8022 (production), 3000 (development)

Bind Address Priority

1. --bind CLI argument
2. BIND environment variable
3. config.json bind setting
4. Default: 0.0.0.0

See Configuration for details.

🔒 HTTPS on Local Network (PWA / "Not Secure" Warnings)

When accessing sshift from a LAN IP (e.g., https://192.168.1.50:8022), browsers show "Not Secure" warnings because the self-signed certificate is untrusted. This also blocks PWA installation.

Quick Fix: Chrome Flag

1. Go to chrome://flags/#unsafely-treat-insecure-origin-as-secure
2. Enter your LAN URL: https://192.168.1.50:8022
3. Set to Enabled → Relaunch

Permanent: Custom Trusted Certificate

Generate a cert for your LAN IP and configure sshift to use it:

{
  "enableHttps": true,
  "certPath": "/path/to/sshift-lan-cert.pem",
  "keyPath": "/path/to/sshift-lan-key.pem"
}

Then add the certificate to your device's trusted root store. See Configuration > HTTPS on Local Network for full instructions including nginx reverse proxy and mDNS options.

🤖 AI Attention Plugins

SSHIFT includes built-in plugins that detect when AI coding tools are waiting for user input and flash the browser tab to get your attention — perfect for when you're multitasking across tabs.

OpenCode Attention

Detects when OpenCode is waiting for input by tracking its spinner characters (⬝ ■ ▣) and prompt patterns. When the spinner stops or a prompt appears, the tab flashes.

Claude Attention

Detects when Claude Code is waiting for input by tracking its spinner characters (⠋⠙⠹ braille patterns, ·✢✳✶✻✽) and prompt patterns like "❯", "Do you want", "Allow", and "Esc to cancel".

Enabling Plugins

Add plugins to your config.json:

{
  "plugins": [
    {
      "name": "opencode-attention",
      "enabled": true,
      "config": {
        "debounceMs": 300,
        "flashDuration": 0,
        "idleThreshold": 3000
      }
    },
    {
      "name": "claude-attention",
      "enabled": true,
      "config": {
        "debounceMs": 300,
        "flashDuration": 0,
        "idleThreshold": 3000,
        "cooldownMs": 1000
      }
    }
  ]
}

See Configuration > Plugins for full details.

🛠️ Technology Stack

Backend: Node.js, Express, Socket.IO, ssh2
Frontend: xterm.js, xterm addons
Development: ESLint, Puppeteer

🤝 Contributing

Contributions are welcome! See Contributing for guidelines.

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• xterm.js - Terminal emulator for the web
• ssh2 - SSH2 client and server modules
• Socket.IO - Real-time bidirectional event-based communication

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Made with ❤️ by the SSHIFT Team