Authentication

Link the CLI to your account

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}

You only need to do this once per machine. Every later command — HTTP, TCP or UDP — authenticates itself with the stored token.

Where the token is stored

The token is written to a file in your home directory. On macOS and Linux the CLI also restricts it to owner read/write, so other users on the machine cannot read it.

~/.port-buddy/token           # macOS, Linux
%USERPROFILE%\.port-buddy\token   # Windows

Running portbuddy init again overwrites the file, which is how you switch accounts. Deleting the file logs this machine out.

How a tunnel authenticates

The API token is long-lived and never leaves your machine except to be exchanged. Each time you start a tunnel, the CLI trades it for a short-lived JWT and uses that for the tunnel connection itself, so the token is not attached to the traffic your tunnel carries.

This exchange happens before the tunnel opens, which is why an expired or revoked token fails immediately rather than halfway through a session.

Revoking access

Delete a token on the Tokens page to cut off every machine holding it. The next command on those machines stops with an authentication error and a reminder to re-run portbuddy init. Issue one token per machine if you want to revoke them independently.

Docker and CI

There is no interactive login, so an automated environment only has to put the token file where the CLI looks for it. In the official image that path is /root/.port-buddy/token — mount it from the host rather than baking it into an image layer.

docker run -v ~/.port-buddy/token:/root/.port-buddy/token:ro \
  amaktech/portbuddy:latest 3000

The same trick works in CI: write the token from a secret to ~/.port-buddy/token before the first tunnel command, or call portbuddy init with the secret as its argument.

Before you start

The CLI has to be on your machine first — see the installation guide for Homebrew, PowerShell and direct-download options. The server also requires a recent CLI and will refuse an old one with an upgrade notice, so update before debugging an authentication failure further. The full list of arguments accepted by the binary is in the CLI reference.