ShellHub Documentation

The API Service is the central component responsible for managing the core logic of the ShellHub platform. Its primary responsibilities include:

• Device Admission: Managing how new devices are admitted into the network.
• Session Management: Handling active user and device sessions.
• Authentication: Managing identity for both users and devices.
• Protocol Bridging: Bridging WebSocket connections to SSH, enabling web-based terminal access.

ShellHub is a centralized SSH gateway designed for remote access to Linux devices over the internet. It eliminates the need for public IPs, VPNs, or manual firewall changes by reversing the connection model.

Core Connectivity Model

Instead of opening inbound ports on devices, you install a lightweight agent on the target device. The agent initiates an outbound connection to the ShellHub server over HTTPS (port 443). This allows access through the ShellHub gateway even if the device is behind NAT, CGNAT, or strict corporate firewalls.

ShellHub acts as a centralized SSH gateway for Linux servers and IoT devices. Key capabilities include:

• Native SSH/SCP/SFTP Support: Use standard tools like OpenSSH Client, PuTTY, or SCP to manage devices without third-party apps.
• SSH Port Forwarding: Securely forward TCP traffic to remote services or use SOCKS Proxy.
• Security & Access Control: Supports public-key authentication, fine-grained SSH firewall rules, and audit logging for all connections.
• Session Recording: Interactive SSH sessions are recorded and can be replayed via the ShellHub Web UI.
• Container Remote Access: Seamless integration with Docker to securely connect to and manage containers.

The ShellHub Agent provides several key capabilities for remote device management:

• Secure Communication: Establishes encrypted connections between the device and the ShellHub server.
• Device Registration: Automatically registers new devices with the ShellHub server upon installation, making them visible in the web interface.
• Authentication and Access Control: Manages user authentication and enforces permissions defined by administrators.
• Session Management: Handles SSH sessions initiated via the ShellHub web interface.
• Heartbeat and Health Checks: Sends regular heartbeat signals to the ShellHub server to monitor device availability and health.

ShellHub supports several key integrations for managing and developing on your devices:

• Ansible: Automate configuration management and deployments across your fleet.
• Terraform: Provision infrastructure with the ShellHub agent pre-installed.
• CI/CD Pipelines: Deploy, test, or provision devices from platforms like GitHub Actions or GitLab CI.
• VS Code Remote SSH: Develop directly on remote devices using the VS Code Remote SSH extension.

The gateway serves as ShellHub's entry point. Its primary responsibilities are terminating TLS and routing inbound HTTP requests and WebSocket connections to the server and the console.

Key architectural details:

• Routing Only: It does not handle authentication or subdomain resolution; those are managed by the API.
• Embedded Caddy: The binary embeds Caddy as a library. It builds a Caddyfile from environment variables at startup, converts it to JSON, and loads it in memory. No configuration files are written to disk.
• Stateless Configuration: Configuration is driven entirely by environment variables. A change in configuration requires a new container/process startup.

ShellHub manages user accounts automatically during the SSO flow based on whether the email in the SAML assertion matches an existing account:

• First-time users: ShellHub automatically creates a new account using the email and name provided in the assertion. These accounts do not have a password and rely entirely on the IdP for authentication.
• Existing users: ShellHub matches the assertion email to the existing account and enables SAML for that user. This preserves existing login methods (e.g., a user with a password can still use either their password or SSO).
• IdP Migration: If you switch to a new IdP, existing SAML users are migrated automatically without requiring manual action.

A namespace is an isolated workspace within ShellHub. It provides complete separation for resources, allowing you to manage different environments, projects, teams, or customers on a single ShellHub server.

Everything in ShellHub is scoped to a namespace, including:

• Devices: Each device belongs to exactly one namespace.
• Sessions: Session history is isolated per namespace.
• Public keys: SSH keys are scoped to the namespace.
• Firewall rules: Rules apply only within the namespace.
• Tags: Tags exist within a namespace.
• Web endpoints: Endpoints are per namespace.
• Team members: Members and their specific roles are scoped to the namespace.
• Settings: Configuration for recording, announcements, and MFA is per namespace.

ShellHub is purpose-built for SSH access to specific devices rather than providing full network-level access like a VPN.

Note: ShellHub is not a replacement for a VPN if your use case requires full network-level connectivity.