Managing Devices
Every machine running an agent appears under Devices.
How a device enrols
Installing the agent is half of it. The other half is the device joining a namespace, and what the agent was given at install decides both how it joins and whether anybody has to act on it.
| Given | Lands | Good for |
|---|---|---|
| Nothing | Accepted, once somebody opens the link it prints | A device in front of you |
| A provisioning key | Whatever the key’s mode says | Fleets, images, production |
| A tenant ID | Pending, for review | Deprecated; what a legacy namespace accepts |
Given nothing, the agent pairs: it asks the server for a code, prints it with a link, and waits for somebody to accept it in the browser. That is the path the Quickstart walks, and the one to use for a machine you are standing at.
A provisioning key is the answer at any volume. It names the namespace on its own and its mode decides acceptance, so a fleet arrives accepted and tagged instead of arriving as a queue.
A tenant ID also names the namespace, and is how a legacy namespace enrolls every device: it always leaves the device pending, in the queue behind the namespace’s built-in key. A new namespace still accepts it the same way, but it is deprecated, so nothing new should use it.
Statuses
| Status | Meaning |
|---|---|
accepted |
In the namespace and reachable |
pending |
Enrolled, waiting to be accepted. Cannot be connected to |
rejected |
Explicitly refused |
removed |
Deleted from the namespace |
unused |
Registered but never used |
Only accepted devices can be connected to. A device sitting in pending is not broken — it is waiting for somebody, on the activity of the key it enrolled with — see Provisioning Keys.
Online and offline
Separate from status. A device is online while its agent holds a connection to the server, and offline when it does not.
The agent sends a keepalive every 30 seconds by default and reconnects on its own, waiting a random 5 to 65 seconds before each attempt, so a brief network problem resolves itself without anybody doing anything. A device that stays offline has a real cause — see Device Not Appearing.
What identifies a device
The agent’s private key, at SHELLHUB_PRIVATE_KEY. Not the hostname, not the MAC, not the IP.
The consequences are worth internalizing:
- Rename the machine and it is the same device.
- Move it to another network and it is the same device.
- Lose the key — reflash, recreate the container, wipe the volume — and it is a new device, and the old entry stays behind.
Most confusing device lists are the result of that last one.
Names
A device’s name defaults to its hostname and is what you type in an SSHID:
$ ssh [email protected]@cloud.shellhub.ioYou can rename a device in the console. Set SHELLHUB_PREFERRED_HOSTNAME on the agent when the
system hostname is not meaningful — a container with a random name, or a fleet where every unit
reports the same one.
Names matter beyond typing: the legacy public key ACL and firewall rules can select devices by a hostname pattern, so a naming convention is something you can write rules against there. Access policies select by tag instead — see Tags.
Details
Opening a device shows its SSHID with a copy button, plus what the agent reports about it — OS, architecture, agent version, when it was last seen.
The agent version is the first thing to check when something behaves oddly on one device and not another.
Rejecting and removing
Rejected refuses the device and keeps the record, so the refusal is still visible later. Removed deletes it from the namespace.
Neither stops the agent. If it is still running with the same key and configuration, it re-enrolls — and depending on how it enrolls, may come straight back.
To retire a device properly: stop the agent on it, then remove it here.
Where to go next
- Tags — Grouping devices so policies can select them.
- Provisioning Keys — Enrolling without a manual step.