Troubleshooting

The installer says Docker is not installed

curl -fsSL https://get.docker.com | sudo sh

Then run the installer again.

The installer cannot connect to Docker

Run it with sudo, as shown in Quick install. If Docker itself is stopped, start it:

sudo systemctl start docker

The image will not build

The machine needs outgoing HTTPS access to hopbits.io (to download SHA256SUMS and the verified agent binary) and gcr.io (for the gcr.io/distroless/static-debian12:nonroot base layer) to build hopbits/agent:local. If you mirror images in your own registry, pass HOPBITS_IMAGE to the installer.

There is no pairing code in the log

• Give the node a few seconds, then read the log again with sudo docker logs hopbits-agent.
• Check that the container is running: sudo docker ps --filter name=hopbits-agent.
• The code is a warning line. It does not show with HOPBITS_LOG_LEVEL=error.
• The node connects outbound over WebSockets to wss://api.hopbits.io/v1/node on port 443. A firewall or proxy that blocks outbound HTTPS or WebSocket upgrades to api.hopbits.io will stop it.

The code was not accepted

A code is valid for 15 minutes. Read the log again and use the newest one.

The node shows as offline

Look at the log for the reason, then restart the container:

sudo docker logs --tail 50 hopbits-agent
sudo docker restart hopbits-agent

The node does not run ping checks

On the host's network a node can only ping when the host allows it. Ping checks in host mode has the one setting to change.