Port Tunneling

This doc explains the panel's "Port Tunneling" feature — mapping the app ports on a tunneled server without a public IP to public ports on the panel server, so external users can access them.

One-line understanding

Your server is hidden on a private network (no public IP), and it runs a website or app that outsiders can't reach. Port Tunneling "opens a public port on the panel server and carries outside access through an encrypted tunnel to your private server's app port". Result: outsiders visiting panel-server-IP:port reach the app on your private server.

Feature overview

For no-public-IP servers connected via "Tunneling", their apps (like Navidrome music, Nextcloud storage, Memos notes) cannot be accessed externally. Port Tunneling maps these app ports to ports on the panel server (which has a public IP), letting external users access them via "panel server IP:port".

Use cases

• A tunneled server runs a web app and you want external access
• Expose services on private-network devices to the public internet
• Give websites, APIs, or panels on no-public-IP devices a public entry point

How it works (how data flows)

external user → panel server public port (e.g. :9117) → encrypted tunnel → tunneled server app port (e.g. :9117)

External traffic first reaches the panel server (the only place with a public IP), then travels through an encrypted reverse tunnel to the private device, finally landing on the app port actually running on the device.

Unified channel (all devices, no manual selection needed):

The panel uniformly uses the 4433 reverse tunnel; when creating a tunnel you don't need to care about the underlying channel or select one manually.

> Additional note: Android/Termux devices' System Panel (command execution, terminal, files) goes over the SocketIO stable channel; but Port Tunneling uniformly uses the 4433 reverse tunnel — the two have their own roles and don't interfere.

How to use

1. Make sure the target device is connected via "Tunneling" (Agent online)

2. Open "Port Tunneling" and click "Add Tunnel"

3. Select the tunneled server (Agent), and fill in:

• Listen port: the public port on the panel server (for external access), e.g. 9117
• Target port: the app port on the tunneled server, e.g. 8080

4. After creation, external users can access http://panel-server-IP:listen-port

Example

Suppose the panel server's public IP is 203.0.113.10, and you have a private Raspberry Pi running Navidrome (listening on 4533):

• Listen port: 4533
• Target port: 4533
• After creation, external users visiting http://203.0.113.10:4533 can open Navidrome on the Raspberry Pi

Resource limits

Exceeding the limit automatically rejects new connections, without affecting running tunnels.

Notes

1. Cloud firewall: the panel server's cloud firewall / security group must allow the corresponding listen port, otherwise external access won't work.

2. Agent version: forwarding non-SSH ports (non-22) requires the tunneled server to have the new Agent installed (the old one only supports forwarding port 22). To forward other ports, reinstall the Agent.

3. Agent online: tunneling depends on the Agent staying online. When the Agent is offline the tunnel breaks; it recovers automatically after reconnect.

4. Panel restart auto-recovery: after the panel service restarts, tunnels recover automatically (triggered when the Agent reconnects).

5. Android target service must support concurrency: if the tunneled target service on Android (e.g. python3 -m http.server) is single-threaded with keep-alive enabled, an unclosed connection will block subsequent requests. It's recommended that the target service be multi-threaded, or ensure connections close promptly.

Related docs

• Tunneling — first connect no-public-IP devices to the panel
• Port Forwarding — traditional port forwarding for public-IP servers (see below for the difference)

Port Tunneling vs Port Forwarding (which to choose)

In one line: no public IP → tunneling; public IP → forwarding.