DEV Community

Andrew
Andrew

Posted on Edited on

How to Remotely Access and Manage IoT Devices Behind NAT or CGNAT

Managing IoT devices like Raspberry Pi boards in the field is a classic headache. They sit behind home routers, CGNAT, or cellular links, and there is no public IP or open port to reach them. The fix is simple: stop trying to connect into the device, and let the device connect out to you. A single outbound connection to a relay service opens a secure path that works from anywhere, and on top of that path you can build the three core jobs of remote management: a shell to act, health data to watch, and a safe way to make changes. In this guide I will show you how to do all three on a Raspberry Pi class device using Pinggy, with one install command and a handful of CLI commands.

Blog Image

Here is the short version. To get a shell, run curl -fsSL https://pinggy.io/install.sh | sh on the device, then open the Terminal tab on its page in the Pinggy Devices dashboard. To survive reboots, run pinggy daemon service-install so the agent starts with the machine. To reach other services, use ssh -p 443 -R0:localhost:22 tcp@free.pinggy.io to publish SSH, VNC, or a web UI as a TCP address, and make it permanent with pinggy config save. For monitoring, check the Overview tab and a small health script. Update one device first, and revoke access by deleting a device or rotating its token.

The three jobs of managing a remote device

Remote management always comes down to reaching, observing, and changing the device. Reaching is the hard part because a device behind NAT, CGNAT, or a corporate firewall has no address you can connect to. The answer is an outbound tunnel. The device dials out and keeps the connection open, and your session rides back along that same connection, so nothing has to be opened on the router. Observing and changing become much easier once you have a shell, so that is where we start.

Step 1: Connect the device and open a shell

On the device, run:

curl -fsSL https://pinggy.io/install.sh | sh
Enter fullscreen mode Exit fullscreen mode

The script does not require sudo. It installs the Pinggy CLI to ~/.pinggy/bin, asks for your email, sends a 6-digit code, and starts the device agent in the background. A new email gets a free account. The agent keeps one outbound connection to the dashboard, so the device needs no open port, no public IP, and no SSH server. Once the agent is running, open the device page in the Pinggy Devices dashboard, go to the Terminal tab, and click New shell. You get a shell that runs as the user who started the agent.

The agent is a small background process. It registers with the Pinggy relay, authenticates with the device token, and holds a persistent connection. The dashboard can then request a shell session, and the agent creates a local PTY. This design means the device does not need to accept any inbound connections. Even if it is behind multiple layers of NAT, the outbound connection is enough.

Blog Image

Typing an email on every unit does not scale. For a device with no keyboard, click Add device in the dashboard and run the command it shows. That command carries the device token and asks for no email or code:

curl -fsSL https://pinggy.io/install.sh | DEVICE_AGENT_TOKEN=<TOKEN> sh
Enter fullscreen mode Exit fullscreen mode

Blog Image

The token reaches the CLI through an environment variable, never on a command line. One machine holds one device credential, so a fleet means one device and one token per unit. The Linux builds are glibc binaries for x64 and arm64, so use 64-bit Raspberry Pi OS. On Alpine and other musl systems, install with the npm CLI: npm install -g pinggy.

The agent stops when the machine reboots unless you install it as a service. Run pinggy daemon service-install once to register the Pinggy daemon as a systemd user service on Linux, a launchd agent on macOS, or a scheduled task on Windows. The device agent starts with the daemon. On Linux, the CLI also enables systemd lingering for your user so the agent can start at boot with nobody logged in. If it cannot, it prints the loginctl enable-linger <user> command for you to run yourself. This arrived in CLI 0.6.5, and pinggy daemon service-uninstall removes it.

Step 2: Reach SSH, VNC and web UIs with a TCP tunnel

A browser shell covers most tasks, but sometimes you want a real SSH session for scp, VNC for a desktop, or a local web UI. Pinggy's SSH IoT guide gives the one-liner, which you run on the device:

ssh -p 443 -R0:localhost:22 tcp@free.pinggy.io
Enter fullscreen mode Exit fullscreen mode

It prints a public address like tcp://rndnj-103-170-183-11.a.free.pinggy.online:37315. From your laptop you can then run:

ssh -p 37315 username@rndnj-103-170-183-11.a.free.pinggy.online
Enter fullscreen mode Exit fullscreen mode

Change the local port from 22 to 5900 for VNC, or 1880 for a Node-RED editor. Reverse TCP tunnels are useful beyond SSH. A local web UI on port 3000, a VNC server on 5900, or a custom protocol on any port can be published the same way. The -R0:localhost:22 syntax tells the relay to reserve a remote port and forward it to port 22 on the device. The public address is random on free, stable with Pro. On the free plan the port changes on every connection and a tunnel lasts 60 minutes, so it is fine for a one-off fix. With a Pro token, the same tunnel gets a persistent address and port.

For a tunnel that should always be there, save it with the CLI instead of keeping a command running. The following commands were tested on CLI 0.6.4, where saving, showing, and deleting a config worked as documented:

pinggy config save iot-ssh --auto --type tcp -l 22 <TOKEN>@pro.pinggy.io

pinggy start --all      # start every auto-start tunnel

pinggy ps               # list running tunnels
Enter fullscreen mode Exit fullscreen mode

Tunnels saved with --auto are the auto-start ones, and pinggy daemon start lists which configs will auto-start. Use pinggy config show iot-ssh to confirm what was saved. These tunnel commands come straight from the docs because I did not open a live tunnel from the test machine. If you change the configuraton, just run the save command again with the new values.

Step 3: Watch the device health

The Overview tab shows the hostname, OS, CPU, memory, and agent version next to live CPU, load average, and uptime. The Activity tab lists events with source IP addresses. It does not show disk space or board temperature, and Pinggy has no alerting that I could find in its docs, so pair it with a small script you can run from the browser shell:

#!/bin/sh

echo "host:   $(hostname)"
echo "uptime: $(uptime | sed 's/^.*up //')"
echo "disk:   $(df -h / | awk 'NR==2 {print $5 " of " $2 " used on /"}')"

if [ -r /proc/meminfo ]; then
  awk '/MemTotal/ {t=$2} /MemAvailable/ {a=$2} END {printf "memory: %d of %d MB available\n", a/1024, t/1024}' /proc/meminfo
fi

if command -v vcgencmd >/dev/null 2>&1; then
  echo "temp:   $(vcgencmd measure_temp | cut -d= -f2)"
fi
Enter fullscreen mode Exit fullscreen mode

I ran this on macOS and in a Debian 12 container, and the disk and memory lines printed correctly. The vcgencmd line only runs on Raspberry Pi OS because that tool exists only there, so I could not test it here. SD card wear is the classic Pi failure, so if you care about it, look at the SD card monitoring options in the tools compared in our device management comparison. You can also schedule the health script with cron or a systemd timer, and write the output to a file that you can fetch over SSH. That gives you historical data without adding another service.

Step 4: Change things without bricking the device

Pinggy Devices has no over-the-air update system and no fleet-wide jobs, so every change is something you do in a shell, one device at a time. That works for ten Pis and stops working for a thousand. For firmware or image updates with rollback, add a dedicated updater such as Mender or balenaCloud.

A few habits keep manual changes safe. Update one device first and let it run for a day before touching the rest. A browser shell ends after 30 minutes with no activity or after 8 hours, so run long jobs under tmux or screen on the device, or teh job dies with the shell. And keep a second way in: if an update breaks the Pinggy agent, a saved TCP tunnel or a plain SSH reverse tunnel is your only path back. Never reboot a device you cannot reach any other way without checking that its agent starts at boot.

Before changing a production device, create a backup of any configuration you plan to edit. If the device is running a containerized workload, snapshot the image or pin the version. Small changes should be done through a single shell session, and the output should be logged.

Step 5: Lock down access

Anyone signed in to your Pinggy account can open a shell on every device as the user running the agent, so turn on 2-factor authentication for the account and run the agent as an unprivileged user, not root. The device token sits in ~/.config/pinggy/device.json, readable only by that user. The agent never logs what you type, and the screen copy that redraws a reopened tab stays in memory.

To cut a device off, delete it in the dashboard or rotate its token. pinggy device remove only forgets the token on the device, so a device whose token leaked needs the dashboard. Token rotation is the fastest way to remove access without touching the hardware. Rotate the token in the dashboard, then run the install command again on the device with the new token. The old token is rejected immediately. Pricing is simple: the Free plan covers 1 device with 1 shell, and Pro is $2.50 per seat per month billed annually, with 25 devices and 25 open shells per seat.

Troubleshooting

If a second device fails to connect on the Free plan, the CLI says Your plan allows 1 device. Delete one in the dashboard, or upgrade, to add another. If the Terminal tab is greyed out, the CLI on that device is too old, so run the install command again. If the agent stops with a message that its token was refused or revoked, the device was deleted or its token rotated, and you need to add it again. If you recieve a message that the Linux uses musl libc, install with npm as shown above.

Conclusion

A remote device needs three things: a way in, a way to see how it is doing, and a safe way to change it. Pinggy Devices gives you the first with one install command and a boot service, a TCP tunnel covers SSH and VNC, and a short script fills the monitoring gap. For updates at scale you will still want a dedicated OTA tool, but for a handful of Pis behind CGNAT this setup takes minutes, not days.

Reference

Top comments (0)