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. Uses sudo because the config file is owned by root.

sudo needports config
sudo 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. These read the local config, so use sudo:

sudo needports doctor
sudo needports connectivity

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

sudo 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.

See and label your assigned ports

List your dedicated public ports and the local targets they forward to. Commands that read or change the local config use sudo, since the config file is owned by root.

sudo needports ports

Give a port a friendly name so it is easy to recognize later:

sudo needports name <assigned-port> "My app"

Publish a local service in one command

Map one of your assigned public ports to a well-known local service without editing any config by hand. List the built-in templates:

needports templates

Built-in templates and their default local ports:

home-assistant  local 8123   Home Assistant dashboard
minecraft       local 25565  Minecraft Java server
http            local 80     Plain HTTP web service
https           local 443    HTTPS web service
ssh             local 22     SSH server
plex            local 32400  Plex Media Server
jellyfin        local 8096   Jellyfin media server
navidrome       local 4533   Navidrome music server
immich          local 2283   Immich photo server
ollama          local 11434  Ollama API
open-webui      local 8080   Open WebUI
jupyter         local 8888   Jupyter notebook/lab

Map an assigned port to a template, then restart to apply:

sudo needports use <template> <assigned-port>
sudo needports restart

For example, publish a Jellyfin server on one of your ports:

sudo needports use jellyfin <assigned-port>
sudo needports restart

The guarded expose form requires an explicit public port and confirmation, and supports a custom local port and label for anything not covered by a template:

sudo needports expose <template> --public-port <assigned-port> --confirm
sudo needports expose custom --public-port <assigned-port> --local-port <local-port> --name "My app" --confirm

Security note: exposing SSH, admin dashboards, metrics endpoints, DNS, Jupyter, Open WebUI, Ollama, and other private services makes them reachable from the public internet. Only publish services you intend to be public, and protect them with their own authentication.

Guided self-host setup preview

Preview a guided setup flow that detects local services and suggests mappings, without changing anything:

sudo needports setup --dry-run
sudo needports wizard --dry-run

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