Introduction

How it works

Port Buddy works as a reverse proxy. When you run the CLI, it establishes a secure connection to our edge servers. Any traffic sent to your unique Port Buddy URL is then proxied through this connection to your local machine.

Installation

Before you can start using Port Buddy, you need to install the CLI on your machine. We provide binaries for macOS, Linux, and Windows.

Authentication

To use Port Buddy, you must be authenticated. This allows us to manage your tunnels and respect your subscription limits.

1. Log in to your account at portbuddy.dev.
2. Go to the Tokens page and generate a new API token.
3. Run the following command in your terminal:

portbuddy init {YOUR_API_TOKEN}

HTTP Tunnels

HTTP is the default mode for Port Buddy. It's used for web applications and APIs.

Usage

portbuddy 3000

This command will expose your local web server running on port 3000. You will receive a public URL like https://abc123.portbuddy.dev.

TCP Tunnels

TCP mode allows you to expose any TCP-based service, such as databases or SSH.

Usage

portbuddy tcp 5432

This command exposes your local PostgreSQL database on port 5432. You will get an address like net-proxy-3.portbuddy.dev:43452.

UDP Tunnels

UDP mode is useful for game servers, VoIP, and other UDP-based protocols.

Usage

portbuddy udp 19132

Run as 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.

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

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:

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

./setup-service.ps1 tcp 22

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

Custom Service Name

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

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

Managing the Service

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

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

Custom Domains

With a Pro or Team plan, you can use your own domain name for your tunnels. We handle the SSL certificate issuance and renewal for you automatically.

Configure your custom domains in the Domains section of the dashboard.

Pricing & Limits

Port Buddy offers two simple plans to suit your needs.