Add a device

The PiPort agent is a small service on your device. It keeps an outgoing, encrypted connection to PiPort, so you can reach the device from anywhere without opening ports.

Supported systems

• Raspberry Pi OS Bookworm and Trixie, 32-bit and 64-bit (every Raspberry Pi, including Zero and 1)
• Debian 11, 12 and 13
• Ubuntu 22.04 and 24.04, Server and Desktop, also Ubuntu for Raspberry Pi

The device needs outgoing internet access (HTTPS) and a user who may use sudo.

Add a device

In the dashboard, open Devices → Add device, choose “One device” and create the token. Then run the two commands it shows on the device, in a terminal or over SSH:

(curl -fsSL https://get.piport.io/install.sh || wget -qO- https://get.piport.io/install.sh) > install.sh
sudo bash install.sh ppe_…

The first line downloads the installer (with wget if curl is missing, as on Ubuntu Desktop). The second installs the agent from the PiPort package repository, connects the device with the token and starts the agent. After a few seconds the device shows up in your dashboard. The token is used once and is not stored on the device.

Several devices and cloned SD cards

Choose “Several devices” to get a token for up to 25 devices that stays valid for 7 days. Run the same two commands on each device; the installer asks for the token, so it stays out of the shell history. Revoke the token in the token list when you are done.

To prepare one SD card and copy it, run the installer with --golden-image as the last step, then shut down and copy the card without booting it again:

sudo bash install.sh --golden-image
sudo poweroff

Every copy connects as its own device on its first boot. A card copied from a device that is already connected is recognised as a copy and asks for a new token instead of taking over the original device.

Update

Run the installer again, without a token. It installs the newest agent and keeps everything else as it is:

(curl -fsSL https://get.piport.io/install.sh || wget -qO- https://get.piport.io/install.sh) > install.sh
sudo bash install.sh

Remove

sudo bash install.sh --uninstall

This keeps the device’s identity, so installing again reconnects it without a token. Add --purge to delete it too. Remove the device in the dashboard as well.

What the installer changes

• the package piport-agent and the PiPort APT repository (signed)
• the service piport-agent, which runs as its own user piport, not as root
• /etc/sudoers.d/piport, which lets that user run exactly three things: restart the device, install an agent update and, on a desktop, take a screenshot as the desktop user. Screenshots are not set up on GNOME or KDE with Wayland (as on Ubuntu Desktop), which do not allow them from outside the session.
• /etc/piport/agent.env (settings, e.g. HTTPS_PROXY=… for a proxy) and /var/lib/piport (the device’s identity)

Troubleshooting

systemctl status piport-agent
journalctl -u piport-agent -f

• “PiPort did not accept the token”: it expired, was used up or was revoked. Create a new one.
• The root filesystem is an overlay: with Raspberry Pi’s “Overlay File System” turned on, nothing written to the card survives a reboot. Turn it off in raspi-config, install, then turn it back on.
• The installer writes a log to /var/log/piport-install.log.

Other distributions

For systems without APT there is a tarball with the agent and its service file, without automatic updates. Download it for your architecture from https://get.piport.io/agent/stable/piport-agent_linux_<arm64|armv6|amd64>.tar.gz, unpack it and run sudo bash install.sh --local ppe_… inside.