Features

• Cross-Platform - Works on macOS, Windows (with WSL), and Linux
• Instant Access - Scan QR code to connect from any device
• Multiple Terminals - Tab-based interface with unlimited terminals
• Session Persistence - Reconnect to existing sessions, output preserved
• tmux Integration - Attach to existing tmux sessions seamlessly
• Mobile Optimized - Swipe gestures, on-screen keyboard, haptic feedback
• Secure - Token auth, rate limiting, auto-rotation, HTTPS via tunnel
• Beautiful UI - Clean, dark theme inspired by modern terminals

Quick Start

# Run instantly (no install)
npx terminal-connect

# Or install globally
npm install -g terminal-connect
connect

Scan the QR code that appears, or open the URL in any browser.

Installation

npm (Recommended)

npm install -g terminal-connect

From Source

git clone https://github.com/kalki-kgp/remote-terminal.git
cd connect
npm install
npm start

Usage

Basic

connect                      # Start server with setup wizard
connect --skip-setup         # Skip dependency checks

Options

connect --ngrok              # Use ngrok instead of cloudflared
connect --ngrok-token TOKEN  # Use authenticated ngrok
connect --port 8080          # Custom port (default: 3000)
connect --help               # Show help

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | PORT | 3000 | Server port | | TUNNEL | cloudflare | Tunnel provider (cloudflare or ngrok) | | NGROK_AUTHTOKEN | - | ngrok authentication token | | TOKEN_LIFETIME | 86400000 | Token lifetime in ms (24h) | | TOKEN_ROTATION | 43200000 | Token rotation interval (12h) |

Platform Support

| Feature | macOS | Windows | Linux | |---------|:-----:|:-------:|:-----:| | Basic terminal | ✅ | ✅ | ✅ | | tmux integration | ✅ | ✅ (via WSL) | ✅ | | Auto-start on boot | ✅ | - | ✅ (systemd) |

Windows Setup

The interactive setup wizard will guide you through installing:

1. WSL (Windows Subsystem for Linux) - for tmux support
2. tmux inside WSL

# Manual WSL install (PowerShell as Admin)
wsl --install

# Then install tmux in WSL
wsl sudo apt install tmux

Mobile Features

Swipe Gestures

Swipe left/right on the terminal to switch between tabs.

Keyboard Shortcuts Bar

On mobile, a keyboard bar provides quick access to:

• Ctrl modifier (tap, then tap a letter)
• C/D/Z/L - Quick Ctrl+C, Ctrl+D, Ctrl+Z, Ctrl+L
• Tab/Esc - Tab and Escape keys
• Arrows - Navigation keys

Security

• Token Expiration - Tokens expire after 24 hours
• Auto-Rotation - Tokens rotate every 12 hours
• Rate Limiting - 5 failed attempts = 30-minute block
• HTTPS - Enforced via ngrok/Cloudflare tunnel
• Isolated Sessions - Each visitor has separate terminals

Warning: Never share your access URL or token publicly.

Architecture

┌─────────────────────────────────────────┐
│  Your Computer                          │
│  ├── Express Server (port 3000)         │
│  │   ├── Static files (UI)              │
│  │   ├── WebSocket (terminal I/O)       │
│  │   └── Token auth + rate limiting     │
│  ├── Session Manager                    │
│  │   ├── Multiple PTY sessions          │
│  │   ├── tmux integration               │
│  │   └── Output buffering (50KB)        │
│  └── Tunnel (ngrok/cloudflare)          │
└─────────────────────────────────────────┘
              │
              ▼
      Phone / Tablet / Browser
      ├── xterm.js terminal
      ├── Swipe navigation
      └── Mobile keyboard bar

Troubleshooting

"cloudflared not found"

The setup wizard will auto-install cloudflared. Manual install:

# macOS
brew install cloudflared

# Linux
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
chmod +x cloudflared && sudo mv cloudflared /usr/local/bin/

# Windows - download from:
# https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/

"ngrok session limit reached" (if using --ngrok)

Free ngrok allows 1 tunnel. Solutions:

pkill ngrok                  # Close other ngrok instances
connect                      # Use cloudflared instead (default, free, no limits)

"Port already in use"

lsof -ti:3000 | xargs kill -9

Windows: "tmux not available"

Install WSL and tmux:

wsl --install              # PowerShell as Admin, then restart
wsl sudo apt install tmux  # After WSL is installed

Contributing

Contributions welcome!

git clone https://github.com/kalki-kgp/remote-terminal.git
cd remote-terminal
npm install
npm run dev   # Start with auto-reload

License

MIT © kalki-kgp