How ShellHub Works
ShellHub has two moving parts. A server, which every device and every user talks to, and an agent, which runs on each device you want to reach. Everything else in this documentation is a consequence of how those two behave.
The connection is made by the device
Reaching a machine over the internet normally means the machine has to be reachable: a public address, an open inbound port, or a tunnel you built in advance. That works when you own the network. It stops working the moment the device sits behind carrier-grade NAT, on a customer’s LAN, or on a mobile link.
ShellHub turns the direction around. The agent opens the connection outbound, to the server, and holds it open. When you want to reach the device, your session is routed through the connection that already exists.
The practical consequence is that the device needs exactly one thing from its network: the ability to reach the ShellHub server’s HTTP(S) address. No inbound port, no public IP, no static address, and no change to the network it happens to be plugged into. If the device can load a web page, ShellHub can reach it.
The server
The server is where every agent’s connection terminates and where every user session starts. It registers devices, tracks which ones are online, works out who is connecting, decides whether that person is allowed, bridges the session down the agent’s connection, and records it when recording is switched on.
You can run it yourself or use the managed ShellHub Cloud. Which components it is made of and how to operate them belong to Self-Hosted — from the outside it is one address.
The agent
The agent is a small daemon on the device. It does three things: it connects outbound to the server and keeps that connection alive, it registers the device and reports its hostname and identity, and it serves whatever you ask for over the connection — a shell, a file transfer, a forwarded port, a container session.
It is the only piece that runs outside the server. It never listens for inbound connections.
A few of its behaviors are worth knowing because they show up in troubleshooting. It sends a
keepalive every 30 seconds by default (SHELLHUB_KEEPALIVE_INTERVAL). It re-authorizes with the
server about every 10 minutes, at a random point between 8 and 12 minutes, so devices that connected
together do not all re-authorize at once. When the connection drops
it reconnects on its own, waiting a random 5 to 65 seconds before each attempt and retrying
indefinitely, so a fleet losing its server does not come back in lockstep. It generates a private key on
first run if one is not already at SHELLHUB_PRIVATE_KEY, and that key is what identifies the
device from then on — delete it and the device comes back as a new one.
See Agent Configuration for the full set.
Namespaces
A namespace is the workspace everything else lives inside: devices, members, policies, settings. It has a name you can change, and a Tenant ID — an immutable UUID that devices, API keys and sessions actually reference.
A namespace is either legacy or new, which decides how connections are authorized and how devices enroll. Namespaces created today are new; a legacy one predates identity-based access and can be upgraded once. See How Authorization Works.
SSHID
One server address fronts every device, so the address you type has to say which device you mean.
ShellHub encodes that into the SSH username, the same way web servers used the Host header to
put many sites on one IP:
[email protected]@serverFor example:
$ ssh [email protected]@cloud.shellhub.io| Part | Value | Meaning |
|---|---|---|
root |
SSH username | The unix user on the device |
mycompany |
Namespace | Which workspace |
raspberrypi |
Device hostname | Which device in that namespace |
cloud.shellhub.io |
Server | The ShellHub server address |
The server splits the string on the first @ to get the username, then splits what remains on
the first . to get the namespace and hostname. Because the whole thing is just an SSH
username, every client understands it with no plugin: OpenSSH, PuTTY, scp, sftp, Ansible.
The path a connection takes
- You run
ssh [email protected]@cloud.shellhub.io. - The connection reaches the ShellHub server.
- The server parses the SSHID and resolves the namespace and the device.
- It works out who you are — from the key you presented, a password, or an approval you confirm in the browser.
- It authorizes the connection against the namespace’s access policies.
- It finds the connection the agent already has open.
- Your terminal I/O is bridged down that connection to the agent.
- The agent opens a shell on the device and joins it to the session.
Step 5 happens before the server mints anything for the agent, so a refused connection never reaches the device at all.
The web terminal takes a different route in — your browser opens a WebSocket to the server instead of an SSH connection — and exactly the same route out.
Where to go next
- Ports and Connectivity — What has to be reachable, on both ends.
- Self-Hosted vs. Cloud — Which deployment fits you.
- Quickstart — Put the agent on a device.