Tunneling

This doc explains the panel's "Tunneling" — connecting servers without a public IP to the panel.

One-line understanding

Devices without a public IP (private machines, NAT devices, Android phones) can't be "actively connected into" from outside. Tunneling lets these devices actively "dial out" to the panel server, after which you can operate them just like normal servers.

Feature overview

For devices with no publicly reachable address at all (private machines, NAT devices, Android phones, etc.), direct SSH connection is impossible. Tunneling uses a reverse tunnel to let these devices actively connect to the panel server, after which you can operate them just like normal servers.

How it works

• The panel server (with a public IP) runs a tunnel service
• A lightweight Agent is installed on the target device and actively "dials out" to the panel server
• Once the connection is established, the panel can reverse-SSH to the target device over this tunnel

> In plain terms: the target device is like "actively calling" the panel server; once the call is connected, the panel can control it back through this "dedicated line".

Use cases

• Manage home-network devices (Raspberry Pi, NAS, soft router)
• Manage cheap VPS without a public IP (NAT servers)
• Manage Android phones (Termux environment)

How to use (three steps)

1. Open "Tunneling" and click "One-click install script" to generate a unique command

2. Paste the command onto the target device and run it once (auto-installs Agent + sets up auto-start on boot)

3. About 10 seconds later, the device appears automatically in the panel — you can then SSH connect and use all features

> The install command is deliberately kept short, for easy manual typing before things are set up:

> - Linux (curl): curl -sSL http://server:5501/i/<token> | sudo bash

> - Termux: curl -sSL http://server:5501/t/<token> | bash

> - If already root you can drop sudo; on Alpine use wget -qO- … | sudo bash, on BSD use fetch -o - … | sudo bash

>

> Install location: on Linux it defaults to /opt/sshe-agent (if /opt is missing or not writable the script auto-falls back to ~/sshe-agent without erroring); Termux uses ~/sshe-agent (follows Termux startup).

>

> Passwordless connection: after install, the panel connects to the device using a pre-injected key, so no password entry each time.

Agent-supported environments

> ⚠️ macOS not supported yet: macOS versions differ too much in SSH authentication to guarantee stable cross-version connections, so this version does not provide macOS tunneling access. Please use Linux / Termux devices for Tunneling.

Agent online status

• Online: tunnel connection is normal, ready to operate at any time
• Offline: the device disconnected (shut down, network lost, Agent stopped). Offline records are kept for a while and auto-recover to online after reconnect

> 📌 Server card determination: a tunneled device's "online/offline" is decided by the Agent heartbeat. Once the Agent is online, it dynamically establishes an SSH channel over the tunnel to collect real health data (load / memory / disk / uptime / battery / temperature), just like a normal server.

Notes

1. The Agent is the only program the panel needs to install on the target device (an exception to the "zero footprint" philosophy). Because no-public-IP devices can't be connected to actively, they can only actively dial out.

2. The Agent consumes minimal resources (one Python process + one long-lived connection).

3. The Agent uses an encrypted tunnel for transmission — secure communication.

4. If the device IP changes or the Agent breaks, just re-run the install script to recover.

Relationship with Port Tunneling

Tunneling is responsible for "bringing the device in", and Port Tunneling is responsible for "exposing the app ports on the device to the public internet". The two work together: first use Tunneling to connect a no-public-IP device, then use Port Tunneling to map its apps (like Navidrome, Nextcloud) to public ports on the panel server.