Run as a Service

You can configure Port Buddy to run as a background service. This ensures that your tunnel starts automatically on system boot and restarts if it fails.

We provide helper scripts to set this up easily. You can run these scripts multiple times to set up different tunnels.

Both scripts install the same command you would type by hand, so the machine needs the CLI installed and authenticated first. The service runs under your account rather than a service identity, precisely so it can find the token you saved. The mode is one of http, tcp or udp, and the optional third argument exposes a host other than localhost.

Linux (systemd)

curl -sSL https://portbuddy.dev/setup-portbuddy-service.sh | sudo bash -s -- [options] <mode> <port> [host]

Windows (Scheduled Task)

Run as Administrator:

iwr https://portbuddy.dev/setup-portbuddy-service.ps1 -OutFile setup-service.ps1
./setup-service.ps1 [options] <mode> <port> [host]

Options

--name <name> (Linux) or -Name <name> (Windows) - Custom name for the service.

Example

To expose port 22 (SSH) over TCP and run it as a service:

Linux:

curl -sSL https://portbuddy.dev/setup-portbuddy-service.sh | sudo bash -s -- tcp 22

Windows:

./setup-service.ps1 tcp 22

By default, the service name follows the pattern portbuddy-<mode>-<port>.

Custom Service Name

Linux:

curl -sSL https://portbuddy.dev/setup-portbuddy-service.sh | sudo bash -s -- --name my-ssh-service tcp 22

Windows:

./setup-service.ps1 -Name my-ssh-service tcp 22

Managing the Service

Linux (systemctl):

sudo systemctl status portbuddy-tcp-22
sudo systemctl stop portbuddy-tcp-22
sudo systemctl start portbuddy-tcp-22

Windows (PowerShell):

Get-ScheduledTask -TaskName portbuddy-tcp-22
Stop-ScheduledTask -TaskName portbuddy-tcp-22
Start-ScheduledTask -TaskName portbuddy-tcp-22

What the scripts install

On Linux the script writes a systemd unit to /etc/systemd/system/, enables it so it starts at boot, and starts it straight away. The unit waits for the network, runs as the user who invoked sudo, and restarts five seconds after any failure. Request logging is switched off, since nobody is watching the terminal.

On Windows it registers a Scheduled Task that triggers at startup and runs as SYSTEM, with your user profile pinned so the CLI still finds your token. A failed task is retried three times at one-minute intervals, and it has no run-time limit.

Logs

The service writes to the platform's own log, so there is no Port Buddy log file to find:

Linux:

journalctl -u portbuddy-tcp-22 -f

Windows:

Get-ScheduledTaskInfo -TaskName portbuddy-tcp-22

The public address a tunnel was given is printed when it starts, so the log is also where you look it up after a reboot.

Updating and removing

The unit points at the binary that was on your PATH when you installed it, so upgrading the CLI in place needs nothing more than a restart. To change the port or mode, run the setup script again with the new arguments and the same name.

Linux:

sudo systemctl disable --now portbuddy-tcp-22
sudo rm /etc/systemd/system/portbuddy-tcp-22.service
sudo systemctl daemon-reload

Windows:

Unregister-ScheduledTask -TaskName portbuddy-tcp-22

Running several at once

Each run of the script installs one service, named after the mode and port unless you pass a name, so running it again for a different port simply adds a second service. Two tunnels of the same mode and port on one machine need distinct names — and bear in mind that each running tunnel counts against your plan’s concurrent tunnel limit.