# Device Not Appearing

The agent is installed and the device is not where you expect. Work down this page in order — it goes from most to least common.

## Is it waiting to be accepted?

Check the Devices page before anything else. While devices wait, its toolbar shows **Waiting for approval** with how many. It opens the provisioning keys holding them, the tenant-only one included, and each key’s activity accepts or rejects them. In a legacy namespace it links **Pending devices** instead, the history of every device that registered with the tenant ID, where anyone who may accept devices accepts or rejects one that waits and accepts one rejected before. Type part of its hostname in the search above either list to find it among many. It is not broken; it is queued.

Accept it and it comes online. To stop needing to, use a [provisioning key](https://docs.shellhub.io/manage/devices/provisioning-keys). See [Provisioning Keys](https://docs.shellhub.io/manage/devices/provisioning-keys#reviewing-a-pending-enrollment).

## Was it refused for not proving its key?

In a namespace that has [Device signature enforcement](https://docs.shellhub.io/manage/settings#device-signature-enforcement) on, an agent older than 0.27 is refused: it cannot sign the server’s challenge with its device key. The refusal shows up in **Pending devices** as one line per device, with the hostname, address, agent version, last attempt and how many times it tried. The agent keeps retrying and the line stays one line.

There is nothing to accept on that line. Two ways out:

- **Update the agent** to 0.27 or later. Its next attempt signs and the device lands pending as usual.
- **Turn Device signature enforcement off** in **Settings** → **SSH**. The agent’s next attempt lands pending. Anyone who knows the device’s hostname, MAC address, public key and the tenant ID can then authenticate as a device that never signed, so prefer updating the agent.

The agent’s own log shows the refusal as `status_code=403`.

## Is the agent running?

Depends on how it was installed:

```bash
$ docker ps | grep shellhub        # Docker
$ podman ps | grep shellhub        # Podman
$ snap services shellhub           # Snap
$ systemctl status shellhub-agent  # standalone
$ service shellhub status          # FreeBSD
```

If it is not running, the logs say why:

```bash
$ docker logs <container>
$ sudo snap logs shellhub
$ journalctl -u shellhub-agent -n 50
```

## Is the configuration right?

Two variables are required, and a mistake in either produces a device that never appears.

**`SHELLHUB_SERVER_ADDRESS`** — must include the scheme. `https://shellhub.example.com`, not `shellhub.example.com`. Self-hosted deployments often have this pointing at the default Cloud address by accident.

**`SHELLHUB_TENANT_ID`** is deprecated. A device that enrolls with it lands in **Pending** and stays out of the device list until somebody accepts it, so look there first. Snap needs it. Docker, Podman and standalone fall back to pairing mode when it is absent, so an install with no tenant is not misconfigured: it is waiting to be paired. Run `shellhub-agent login` on the host. See [How a device enrols](https://docs.shellhub.io/manage/devices#how-a-device-enrols).

A typo’d variable name is ignored silently, which is a particularly quiet way to fail. Check the spelling against [Agent Configuration](https://docs.shellhub.io/get-started/agent-configuration).

## Can the device reach the server?

From the device:

```bash
$ curl -sS -o /dev/null -w '%{http_code}\n' https://shellhub.example.com/info
```

A `200` means the path is fine and the problem is elsewhere. Anything else is network or DNS, and that is what to fix.

The agent needs only outbound access — no inbound port, no public address. If a browser on that device could load a page from your server, so can the agent. See [Ports and Connectivity](https://docs.shellhub.io/about/ports-and-connectivity).

## Does it show up under a name you did not expect?

The device name defaults to the system hostname. On a fleet where every unit reports the same hostname, or a container with a random one, the device is there but not called what you are looking for.

Set `SHELLHUB_PREFERRED_HOSTNAME` to something meaningful.

## Did an old device come back instead?

If a device you expected to be new appears as an existing entry — or vice versa — the private key is the reason.

`SHELLHUB_PRIVATE_KEY` **is** the device’s identity. The consequences:

- **Same key, new machine** → it is the same device to ShellHub.
- **Key lost** — reflashed, container recreated, volume wiped — → a **new** device, with the old entry left behind.

The second is by far the most common cause of a device list that does not match reality. Put the key on persistent storage.

If you are building images, be sure the key is _not_ baked in — every unit flashed from an image containing a key claims the same identity. See [Yocto](https://docs.shellhub.io/get-started/install/yocto) and [Buildroot](https://docs.shellhub.io/get-started/install/buildroot).

## It appeared, then went offline

Normal, if brief. The agent keepalives every 30 seconds and reconnects on its own, waiting a random 5 to 65 seconds before each attempt, so a short network problem resolves itself.

Staying offline has a real cause. Check the agent is still running, then the network.

**On WSL specifically:** the distribution shuts down when the last terminal closes, and the agent goes with it. See [Install the Agent](https://docs.shellhub.io/get-started/install).

**After a reboot, on Podman:** the container is started by `podman-restart.service`. If it is not running, enable the unit:

```bash
$ sudo systemctl enable --now podman-restart.service
```

An install made with `SKIP_BOOT_RESTART_CHECK=1` is yours to bring back.

## A provisioning key was involved

If the device enrolled with a provisioning key, the key’s mode decides where it lands: `automatic` accepts it, `manual` puts it in Pending, `webhook` asks your endpoint, `allowlist` accepts it only if the identity it reports is listed.

A device rejected by an allowlist or a webhook did enroll — it was refused. Check the key’s history. See [Provisioning Keys](https://docs.shellhub.io/manage/devices/provisioning-keys).

> **Careful**
>
> A webhook that points at an internal address is **not called** unless its range is in `SHELLHUB_PROVISIONING_KEY_WEBHOOK_ALLOWED_CIDRS`, which defaults to blocking private, loopback and metadata addresses.

## Where to go next

- [Managing Devices](https://docs.shellhub.io/manage/devices) — The three ways a device enrols.
- [Agent Configuration](https://docs.shellhub.io/get-started/agent-configuration) — Every variable and its real name.
- [Connection Denied](https://docs.shellhub.io/manage/access-control/connection-denied) — The device is there but refuses you.
