Pinggy Devices

Pinggy Devices connects a machine to the Pinggy dashboard. Once a machine is connected, you can:

• Open a terminal on it from your browser.
• See its hostname, OS, CPU, and memory, with live CPU, load, and memory usage.
• List its tunnels and saved tunnel configs, and start, stop, restart, or edit them.
• See an activity log of what happened on the device, with source IP addresses.

The machine runs the Pinggy CLI as an agent. The agent opens 1 outbound connection to the dashboard and keeps it open. The machine needs no open port, no public IP, and no SSH server, so it works behind NAT, CGNAT, and firewalls.

Add a device

Run 1 command on the machine you want to add.

curl -fsSL https://pinggy.io/install.sh | sh

irm https://pinggy.io/install.ps1 | iex

The command does 2 things:

1. It installs the Pinggy CLI, or updates it. It needs no sudo or administrator rights.
   • macOS and Linux: the binary goes to ~/.pinggy/bin/pinggy, with a link in ~/.local/bin. When ~/.local/bin is not on your PATH, the script adds 1 line to your shell’s rc file.
   • Windows: the binary goes to %LOCALAPPDATA%\Pinggy\bin\pinggy.exe, and that folder is added to your user PATH.
2. It signs the machine in. It runs pinggy device login -b, which asks for your email, prints a Device Code, and sends you a 6-digit code and an Approve sign-in button:
   • Type the code in the terminal, or click the button in the email.
   • If you click the button, approve only when the page shows the same Device Code the terminal printed. A different code means someone else started that sign-in.
   • If your account has 2-factor authentication on, the CLI also asks for your authenticator code.
   • An email with no Pinggy account gets a new free account.

When the sign-in finishes, the CLI prints a link and a QR code to the device’s page in the dashboard, and the commands that manage the device. Then it starts the agent in the background and exits. The agent stays connected after you close the terminal. The device is named after the machine’s hostname.

The Linux binaries need glibc, as on Debian, Ubuntu, and Fedora. On Alpine and other musl-based systems, install with npm install -g pinggy instead.

Add a device from the dashboard

On the Pinggy Devices page, click Add device. The dashboard shows a command with the device’s token in it:

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

$env:DEVICE_AGENT_TOKEN='<TOKEN>'; irm https://pinggy.io/install.ps1 | iex

This command installs or updates the CLI, then connects the machine as that device, with the agent in the background. It asks for no email and no code, and it needs no keyboard, so it also works in CI jobs, in docker run without -t, and on machines you reach only through a script. The token reaches the CLI in an environment variable, never on a command line, and the CLI removes the variable before it starts anything else.

If the CLI is already installed

pinggy device login                     # sign in with your email
pinggy device connect --token <TOKEN>   # or connect with a token from the dashboard

Both run the agent in the background and exit once the device connects. The first successful connect saves the token on the machine, so later runs need only pinggy device connect.

The agent runs in the background

The Pinggy CLI daemon runs the agent, the same daemon that runs background tunnels. The agent keeps running after you close the terminal. Before login and connect exit, they print the commands that manage the device:

Manage this device:
  pinggy device status   Show this device, and whether its agent runs
  pinggy device stop     Stop the agent. The device shows offline
  pinggy device connect  Start the agent again, after a stop or a reboot
  pinggy device remove   Forget this machine's credential

The agent stops with pinggy device stop, when the daemon stops (pinggy daemon stop), and when the machine reboots. After a reboot, run pinggy device connect again. The token is saved, so it asks nothing.

To keep the agent in the terminal instead, add --foreground. It runs until you press Ctrl+C:

pinggy device connect --foreground
pinggy device login --foreground

An older CLI runs the agent in the terminal unless you add -b. Run the install command again to update it.

Open a remote terminal

Open the device in the dashboard and go to the Terminal tab. Click New shell to start a shell on the machine. Each shell gets its own tab.

• A shell keeps running when you close the browser tab, and when the machine’s connection drops for a while. Open the Terminal tab again to go back to it. The screen is redrawn as you left it.
• The shell runs as the user who ran pinggy, with that user’s permissions. On macOS and Linux it is a shell listed in /etc/shells. On Windows it is PowerShell or cmd.exe.
• Ctrl+C works as in a local terminal. It stops the program running in the shell, not the shell.
• On macOS and Linux, each tab shows the shell’s current directory and the program running in it.

A shell ends when you close it or type exit. It also ends:

• After 30 minutes with no activity.
• After 8 hours, whatever its activity.
• When the agent stops: pinggy device stop, pinggy daemon stop, or Ctrl+C on an agent started with --foreground.

If the Terminal tab is greyed out, the CLI on that machine is too old to open a shell. Run the install command again to update it.

Manage tunnels on a device

The Tunnels tab lists the tunnels running on the machine and the tunnel configs saved there with pinggy config save. From it you can:

• Start, stop, and restart tunnels.
• Edit a saved config, or the config of a running tunnel.
• Start a new tunnel on the machine from a config you define in the dashboard.

Tunnels started from the dashboard run in the background on the machine, as pinggy start -b does. Stopping the device agent leaves running tunnels alone. See the Pinggy CLI docs for saved configs and background tunnels.

Plans

See pricing for the plans.

Commands

1 machine holds 1 device credential. Running a second agent with the same credential does not work: the dashboard refuses the second connection while the first one is open.

Security

• The machine only makes an outbound connection. It accepts no incoming connection.
• The device token is saved in device.json in the CLI’s config directory: ~/.config/pinggy/ on macOS and Linux, where only your user can read it, and %APPDATA%\pinggy\ on Windows.
• The agent never logs what you type in a shell. The copy of a shell’s screen that redraws a reopened tab is kept in memory only, and it is gone when the shell ends.
• The Activity tab lists the device’s events, with source IP addresses.
• To revoke a device, delete it or rotate its token in the dashboard. pinggy device remove only deletes the token from the machine. A machine without its token cannot authenticate a delete.

Anyone signed in to your Pinggy account can open a shell on your devices. Turn on 2-factor authentication for your account.

Pinggy Devices and remote management

Remote management is an older feature. It runs pinggy --remote-management <API_KEY> and lets the dashboard create and stop tunnels on that machine. Pinggy Devices covers that and adds the terminal, machine metrics, saved configs, and the activity log. The 2 features use different credentials and can run on the same machine.

Troubleshooting