Client operations

NeedPorts client commands and uninstall guide

Use these commands on the machine where the NeedPorts client is installed. They help you check tunnel health, inspect logs, test assigned ports, refresh configuration, and remove the local client when you no longer need it.

Tip: If the needports helper is installed, use it for normal client operations. Curling the installer is only for first install, repair/reinstall, refresh, or fallback uninstall if the helper is missing or damaged. The lower-level systemctl and journalctl commands are included for servers where you want to inspect the underlying service directly.

Quick checks

Status

Check whether the tunnel client service is running.

needports status
systemctl status frpc

Logs

Follow live tunnel logs while testing or troubleshooting.

needports logs
journalctl -u frpc -f

Config

Show the local tunnel config and assigned remote ports.

needports config
cat /etc/frp/frpc.toml

Restart or stop the tunnel

Restart the client after changing local networking or if you want to force a reconnect to the NeedPorts endpoint.

needports restart
systemctl restart frpc

Stop the local tunnel client without uninstalling it:

needports stop
systemctl stop frpc

Diagnostics and port testing

Run a non-invasive local diagnostic summary:

needports doctor
needports connectivity

To test end-to-end forwarding on one assigned port, replace <assigned-port> with a port from your NeedPorts range:

needports probe <assigned-port>

If you want to run a simple local test service yourself, use:

needports selftest <assigned-port>
needports-selftest <assigned-port>

The probe command refuses to use a port that already has a local service listening, so it does not accidentally interrupt your app.

Refresh or reinstall configuration

If support asks you to refresh the local config or reinstall the service using the existing local token, run one of these:

curl -fsSL https://api.needports.com/install | sudo bash -s --refresh-only
curl -fsSL https://api.needports.com/install | sudo bash -s --reinstall

For self-hosted / generic server installs, you can explicitly refresh in self-hosted mode:

curl -fsSL https://api.needports.com/install | sudo bash -s --reinstall --mode selfhost

Print built-in help

For installed clients, print helper usage and the current operational command list locally:

needports help
needports commands

If the helper is missing or you want the live installer options, use the installer fallback:

curl -fsSL https://api.needports.com/install | sudo bash -s --help
curl -fsSL https://api.needports.com/install | sudo bash -s --print-commands

Uninstall NeedPorts from a machine

Run this on the machine where the NeedPorts client is installed:

sudo needports uninstall

If the helper is missing or damaged, use the live installer fallback:

curl -fsSL https://api.needports.com/install | sudo bash -s --uninstall

This removes the local NeedPorts tunnel client, config, helper commands, and related systemd services from that machine. When possible, it also reports the uninstall event to NeedPorts so support can distinguish an intentional uninstall from a tunnel outage.

Important: uninstalling the local client does not necessarily cancel billing or delete your NeedPorts account. To manage a subscription, use the billing portal link from checkout emails or contact support.

When to contact support

Get dedicated portsBack to guides