Docs

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 pending link on the Devices page before anything else. It opens Pending devices, 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. A device enrolled with a provisioning key waits on that key’s row in Add Device → Fleet instead. It is not broken; it is queued.

Accept it and it comes online. To stop needing to, use a provisioning key. See Provisioning Keys.

Was it refused for not proving its key?

In a namespace that has 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:

$ 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:

$ 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.

A typo’d variable name is ignored silently, which is a particularly quiet way to fail. Check the spelling against Agent Configuration.

Can the device reach the server?

From the device:

$ 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.

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 and 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.

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

$ 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.

Where to go next

esc