Deploying ShellHub

Introduction

ShellHub is a modern SSH gateway that enables secure remote access to devices behind firewalls and NAT. It provides a centralized platform for managing multiple devices, allowing you to access them via SSH through a web browser or traditional SSH clients without complex VPN setups or port forwarding.

Built with a microservices architecture using Go and Vue.js, ShellHub consists of a server component and lightweight agents that run on your devices. The agents establish outbound connections to the server, allowing devices behind restrictive firewalls to be accessible remotely.

Key highlights of ShellHub:

• NAT Traversal: Access devices behind firewalls without port forwarding
• Web Terminal: SSH directly from your browser
• Device Management: Organize devices with namespaces and tags
• Session Recording: Record and replay SSH sessions
• Multi-User Access: Role-based access control for teams
• Firewall Rules: Control which devices can connect
• Public Keys: SSH key management for secure authentication
• Agent for Any Device: Lightweight agent for Linux, containers, and more
• REST API: Automate device management
• 100% Open Source: Licensed under Apache-2.0

This guide walks through deploying ShellHub on Klutch.sh using Docker, connecting devices, and managing remote access.

Why Deploy ShellHub on Klutch.sh

Deploying ShellHub on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh handles the complex microservices setup automatically.

Persistent Storage: Attach volumes for device data and session recordings.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure connections.

Always-On Gateway: Your SSH gateway remains accessible 24/7 for remote access.

Custom Domains: Use your own domain for a professional device management portal.

Prerequisites

Before deploying ShellHub on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your ShellHub configuration
• Basic familiarity with Docker and containerization concepts
• A MongoDB database
• Devices you want to manage (Linux servers, Raspberry Pi, etc.)

Preparing Your Repository

Create a GitHub repository with your ShellHub configuration.

Repository Structure

shellhub-deploy/
├── Dockerfile
├── docker-compose.yml
└── .dockerignore

Creating the Dockerfile

For a single-container deployment, create a Dockerfile:

FROM shellhubio/shellhub:latest

# Environment variables
ENV SHELLHUB_HTTP_PORT=80
ENV SHELLHUB_SSH_PORT=2222
ENV SHELLHUB_ENTERPRISE=false
ENV SHELLHUB_ENV=production

# MongoDB connection
ENV SHELLHUB_MONGODB_URI=${SHELLHUB_MONGODB_URI}

# Secret keys
ENV SHELLHUB_SECRET_KEY=${SHELLHUB_SECRET_KEY}
ENV SHELLHUB_PRIVATE_KEY=${SHELLHUB_PRIVATE_KEY}

# Expose ports
EXPOSE 80 2222

Environment Variables Reference

Variable	Required	Default	Description
SHELLHUB_MONGODB_URI	Yes	-	MongoDB connection string
SHELLHUB_SECRET_KEY	Yes	-	Secret key for JWT tokens
SHELLHUB_PRIVATE_KEY	Yes	-	Private key for SSH authentication
SHELLHUB_HTTP_PORT	No	80	HTTP port for web interface
SHELLHUB_SSH_PORT	No	22	SSH port for connections
SHELLHUB_ENTERPRISE	No	false	Enable enterprise features
SHELLHUB_PUBLIC_URL_DOMAIN	No	-	Public domain for the gateway

Deploying ShellHub on Klutch.sh

Set Up MongoDB

ShellHub requires MongoDB. Deploy a MongoDB instance or use a managed service.

Generate Secret Keys

Generate the required secret keys:

# Secret key for JWT
openssl rand -hex 32

# Private key for SSH
openssl genrsa 4096

Push Your Repository to GitHub

Initialize and push your repository:

git init
git add Dockerfile .dockerignore
git commit -m "Initial ShellHub deployment configuration"
git remote add origin https://github.com/yourusername/shellhub-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project with a descriptive name like “shellhub” or “ssh-gateway”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your ShellHub repository.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 80

Note: SSH access (port 2222) may require additional configuration depending on Klutch.sh capabilities.

Set Environment Variables

Add the following environment variables:

Variable	Value
SHELLHUB_MONGODB_URI	Your MongoDB connection string
SHELLHUB_SECRET_KEY	Your generated secret key
SHELLHUB_PRIVATE_KEY	Your generated private key
SHELLHUB_PUBLIC_URL_DOMAIN	your-app-name.klutch.sh

Attach Persistent Volumes

Add the following volume:

Mount Path	Recommended Size	Purpose
/data	10 GB	Session recordings and cache

Deploy Your Application

Click Deploy to start the build process.

Access ShellHub

Once deployment completes, access your ShellHub instance at https://your-app-name.klutch.sh.

Initial Configuration

Creating Your Account

1. Navigate to your ShellHub instance
2. Click Sign Up to create an admin account
3. Create your first namespace (organization)
4. You’re ready to add devices

Installing the Agent

Install the ShellHub agent on devices you want to manage:

For Linux:

curl -sSf "https://your-app-name.klutch.sh/install.sh?tenant_id=YOUR_TENANT_ID" | sh

For Docker:

docker run -d \
  --name shellhub-agent \
  --restart=always \
  --privileged \
  --net=host \
  --pid=host \
  -v /:/host \
  -e TENANT_ID=YOUR_TENANT_ID \
  -e SERVER_ADDRESS=https://your-app-name.klutch.sh \
  shellhubio/agent

Accepting Devices

1. After installing the agent, the device appears as “pending”
2. Go to Devices in the dashboard
3. Click Accept to approve the device
4. The device is now accessible

Accessing Devices

Web Terminal

1. Click on a device in the dashboard
2. Click Connect
3. Enter credentials
4. You’re connected via the web terminal

SSH Client

Connect using a standard SSH client:

ssh username@device-id.your-app-name.klutch.sh

Or use the namespace format:

ssh username@device.namespace@your-app-name.klutch.sh

SSH Key Authentication

1. Go to Settings > Public Keys
2. Add your SSH public key
3. Assign to specific devices or all devices
4. Connect without passwords

Device Management

Tags and Filtering

• Add tags to devices for organization
• Filter device list by tags
• Create dynamic groups

Firewall Rules

1. Go to Settings > Firewall Rules
2. Create rules to allow/deny connections
3. Base rules on username, IP, or device

Session Recording

When enabled, ShellHub records SSH sessions:

1. Go to Sessions to view history
2. Click a session to replay
3. Use for auditing and troubleshooting

Troubleshooting

Device Not Connecting

Symptoms: Device stays in pending state or disconnects.

Solutions:

• Verify agent can reach the server
• Check TENANT_ID is correct
• Ensure device has internet access
• Review agent logs

Cannot Connect via SSH

Symptoms: SSH connection refused or times out.

Solutions:

• Verify device is online and accepted
• Check SSH credentials
• Ensure firewall rules allow connection
• Try web terminal to isolate the issue

Additional Resources

• Official ShellHub Website
• ShellHub Documentation
• ShellHub GitHub Repository

Conclusion

Deploying ShellHub on Klutch.sh gives you a powerful SSH gateway that simplifies remote access to devices behind firewalls. With web-based terminals, session recording, and multi-user support, ShellHub provides enterprise-grade device management while remaining fully self-hosted.