# Managing Devices

Every machine running an agent appears under **Devices**.

![ShellHub Devices page listing accepted devices](https://docs.shellhub.io/img/shots/device-list.png)

## 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](https://docs.shellhub.io/manage/devices/provisioning-keys) | Whatever the key’s mode says                     | Fleets, images, production                                                                                          |
| A tenant ID                                                                     | Pending, for review                              | Deprecated; what a [legacy namespace](https://docs.shellhub.io/manage/access-control/migrating-from-legacy) 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](https://docs.shellhub.io/get-started) 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](https://docs.shellhub.io/manage/devices/provisioning-keys#reviewing-a-pending-enrollment).

## 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](https://docs.shellhub.io/manage/devices/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:

```bash
$ ssh root@mycompany.raspberrypi@cloud.shellhub.io
```

You 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](https://docs.shellhub.io/manage/devices/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.

![Device details page showing the SSHID with a copy button](https://docs.shellhub.io/img/shots/device-details.png)

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](https://docs.shellhub.io/manage/devices/tags) — Grouping devices so policies can select them.
- [Provisioning Keys](https://docs.shellhub.io/manage/devices/provisioning-keys) — Enrolling without a manual step.
