Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/thenoname-gurl/EcliPanel/llms.txt

Use this file to discover all available pages before exploring further.

EcliTunnel is a TCP tunnelling system built into EcliPanel. It lets users expose a locally running service (a game server, a development API, any TCP service) to the internet through a public port allocation managed by the panel. The system is made up of two Rust agents — a client agent that runs on the user’s machine and a server agent that runs on a publicly reachable host — along with a control plane hosted in the EcliPanel backend.
Tunnels are controlled by the tunnels feature flag. If the flag is disabled, the Tunnels navigation item is hidden and all /api/tunnel/* endpoints are inaccessible.

​
How tunnels work

The control plane (backend WebSocket) coordinates enrollment, approval, and allocation, but tunnel data travels directly between the server agent and the client agent — it does not flow through the backend: 
internet → server agent → client agent → local service
When a public connection arrives at the server agent, it notifies the backend, which issues a one-time direct token. The client then connects to the server allocation port, presents the token, and the server agent bridges the two TCP connections directly. The server agent binds ports from the allocation range (default 20000–29999) dynamically as the backend assigns them.

​
Device enrollment

Both client and server agents must be enrolled and approved before they can connect. The enrollment flow is:
1

Start enrollment

The client agent calls POST /api/tunnel/device/start to begin enrollment and receives a user code.
2

Approve in the panel

A panel admin or the device owner approves the device via POST /api/tunnel/device/approve in the dashboard at /dashboard/tunnels.
3

Connect

The approved agent polls GET /api/tunnel/device/poll until it receives a bearer token, then connects to the GET /api/tunnel/ws WebSocket control channel.

​
Running the client agent

Build and run the client agent from the tunnel/client directory:
1

Enroll the client device

cd tunnel/client
cargo run --release -- enroll --backend https://your-backend.example
2

Run with a new allocation

After approval, start the agent and request a public tunnel allocation in the same command:
cargo run --release -- run \
  --backend https://your-backend.example \
  --local-host 127.0.0.1 \
  --local-port 8080 \
  --protocol tcp
3

Run against an existing allocation

If you created an allocation separately from the dashboard, run without port flags:
cargo run --release -- run --backend https://your-backend.example
To enable verbose logging, add --verbose before the subcommand: 
cargo run --release -- --verbose run --backend https://your-backend.example

​
Running the server agent

The server agent must be enrolled with an admin JWT and then run as a long-lived process:
1

Enroll the server device

cd tunnel/server
cargo run --release -- enroll \
  --backend https://your-backend.example \
  --jwt-token <admin_jwt>
2

Run the server agent

cargo run --release -- --backend https://your-backend.example run --token <access_token>
The server host must allow inbound TCP traffic on the entire tunnel port range (default 20000–29999). Open these ports in your firewall or security group before starting the server agent.

​
Managing allocations from the CLI

Use the allocations subcommand to list, close, or delete your current tunnel allocations interactively: 
cargo run --release -- allocations --backend https://your-backend.example
Within the interactive prompt:
  • Press c to close an allocation (removes the active tunnel but keeps the record)
  • Press d to permanently delete an allocation

​
API endpoints

The following REST endpoints back the tunnel dashboard and the Rust agents:
EndpointDescription
GET /api/tunnel/allocationsList tunnel allocations visible to you
GET /api/tunnel/devicesList your enrolled devices
POST /api/tunnel/device/approveApprove a pending device
DELETE /api/tunnel/devices/:id/deleteDelete a device
POST /api/tunnel/devices/:id/regenerate-tokenRotate a device’s access token
POST /api/tunnel/device/startBegin device enrollment (used by the Rust agent)
GET /api/tunnel/device/pollPoll for enrollment approval (used by the Rust agent)

​
Self-hosting the server agent

When self-hosting, set the TUNNEL_PUBLIC_HOST environment variable on the backend to the public hostname of your server agent host. The panel constructs the public endpoint shown to users as <TUNNEL_PUBLIC_HOST>:<allocated_port>. Make sure TUNNEL_PUBLIC_HOST resolves in DNS to the machine running your server agent before starting any agents. 
TUNNEL_PUBLIC_HOST=tunnel.example.com
Run the server agent as a supervised long-lived process using systemd, a container, or a process supervisor to ensure it restarts on failure.

Build docs developers (and LLMs) love

Get started for freeTalk to us