Skip to main content

​
Overview

suSHi provides a fully-featured web-based SSH terminal that runs directly in your browser. Built with xterm.js and WebSocket technology, it offers a native terminal experience without requiring any local SSH client installation.

​
How It Works

The web terminal establishes a secure connection between your browser and remote machines:
  1. WebSocket Connection: Your browser connects to the suSHi server via WebSocket
  2. SSH Bridge: The server maintains an SSH connection to your target machine
  3. Real-time Data: Commands and output are streamed bidirectionally in real-time

​
Key Features

Open multiple terminal sessions in different tabs within the same browser window:
  • Click the + button in the tab bar to open new terminals
  • Switch between terminals instantly
  • Each tab maintains its own independent SSH session
  • All tabs share the same WebSocket connection for efficiency
Each terminal tab creates its own SSH session, allowing you to work on multiple tasks simultaneously on the same or different machines.

​
Using the Terminal

​
Accessing a Machine

  1. Navigate to your machine list in the dashboard
  2. Click Connect on the machine you want to access
  3. Enter your encryption password when prompted
  4. The terminal opens automatically in a new tab

​
Terminal Interface

The terminal interface includes:
  • Tab Bar: Shows all open terminal sessions
  • Terminal Area: Full-screen terminal emulator
  • Add Tab Button (+): Opens additional terminal sessions
The terminal automatically connects on load using the UUID from your connection request. No manual configuration needed!

​
Working with Multiple Tabs

// Terminal tabs are managed client-side
// Each tab maintains:
{
  tabId: 0,           // Unique tab identifier
  terminal: Terminal, // xterm.js instance
  ws: WebSocket      // WebSocket connection
}

​
Connection Flow

1

Connect to Machine

Click the Connect button on a machine in your dashboard
2

Authenticate

Enter your encryption password to decrypt stored credentials
3

Session Created

Server creates SSH connection and generates a unique UUID
4

Terminal Opens

Browser redirects to terminal page with UUID parameter
5

WebSocket Established

Terminal establishes WebSocket connection using the UUID
6

Start Working

Full SSH terminal access with real-time command execution

​
Technical Details

​
WebSocket Protocol

The terminal uses a custom message format for WebSocket communication: 
{
  "type": "data",        // Message type: 'data' or 'heartbeat'
  "data": "ls -la\n"     // Terminal input/output content
}
Message Types:
  • data: Terminal commands and output
  • heartbeat: Keep-alive ping sent every 5 minutes

​
Connection URL

Terminals connect to WebSocket endpoint: 
wss://your-domain.com/ssh?uuid=<session-uuid>
  • Protocol: WSS (WebSocket Secure)
  • Endpoint: /ssh
  • Query Parameter: uuid (session identifier)
  • Authentication: JWT token (handled automatically)

​
Heartbeat Mechanism

To keep connections alive and track active sessions: 
// Heartbeat sent every 5 minutes
setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({ 
      type: 'heartbeat', 
      data: '' 
    }));
  }
}, 5 * 60 * 1000);
Server-side processing:
  • Updates session activity timestamp
  • Tracks usage for time-bucket analytics
  • Prevents connection timeouts
Heartbeats are rounded to the nearest minute for efficient time-bucket tracking and session management.

​
Browser Support

The web terminal works in all modern browsers that support:
  • WebSocket API
  • ES6 JavaScript
  • HTML5 Canvas (for xterm.js rendering)
Recommended browsers:
  • Chrome/Edge 90+
  • Firefox 88+
  • Safari 14+

​
Best Practices

Save Work Frequently

Don’t rely on browser tabs staying open. Save your work to prevent loss from accidental closures.

Use Screen/Tmux

For long-running tasks, use terminal multiplexers like screen or tmux to persist sessions.

Mind the Bandwidth

Real-time streaming uses bandwidth. Avoid very large outputs or consider pagination.

Secure Your Session

Always log out when done. Don’t leave terminals open on shared or public computers.

​
Limitations

Current Limitations:
  • File uploads/downloads require SCP or SFTP commands
  • Terminal size is fixed (600×800) - not responsive to window resize
  • No built-in clipboard integration (use browser clipboard)
  • Session timeout after extended inactivity

​
Troubleshooting

Possible causes:
  • Invalid or expired UUID
  • SSH connection to machine failed
  • WebSocket connection blocked by firewall
Solutions:
  • Try reconnecting from the machine dashboard
  • Check machine credentials and network accessibility
  • Verify WebSocket traffic (WSS) isn’t blocked
Possible causes:
  • Network latency to remote machine
  • Server under heavy load
  • Remote machine is slow to respond
Solutions:
  • Check your internet connection
  • Verify the remote machine is responsive
  • Consider using a closer geographic region
Possible causes:
  • Character encoding mismatch
  • Terminal type not supported by remote
Solutions:
  • Ensure remote machine supports xterm
  • Set proper locale: export LANG=en_US.UTF-8
  • Check terminal emulation settings

​
Next Steps

Machine Management

Learn how to add and manage your SSH machines

Security

Understand how your credentials are protected

Build docs developers (and LLMs) love

Get started for freeTalk to us