PiTunnel Server

PiTunnel server is a tunnel server that exposes services on your local network to the internet.

Features

• Web Tunnel: HTTP/HTTPS traffic proxying
• TCP Tunnel: SSH, RDP, MySQL, PostgreSQL and other protocols
• Custom Domain: Support for custom domains (clients can use their own domains)
• WebSocket Support: Full bidirectional WebSocket proxy (including HMR support)
• Dynamic Port: Automatic port opening based on client's target port
• API: RESTful API for tunnel management
• Statistics: Request count, bandwidth usage

Quick Install (Recommended)

One-line installer for Linux servers (Ubuntu, Debian, CentOS, etc.):

curl -fsSL https://raw.githubusercontent.com/Pi-Tunnel/Server/refs/heads/main/setup.sh -o /tmp/setup.sh && sudo bash /tmp/setup.sh

This will:

• Install Node.js and dependencies
• Download and configure PiTunnel Server
• Set up systemd service (auto-start on boot)
• Configure firewall rules
• Generate authentication token
• Create piserver CLI command

Server Commands

After installation, use the piserver command to manage the server:

Command	Description
piserver start	Start PiTunnel Server
piserver stop	Stop PiTunnel Server
piserver restart	Restart PiTunnel Server
piserver status	Show server status
piserver logs	View live logs
piserver update	Update to latest version
piserver config	Show configuration
piserver token	Show auth token
piserver help	Show help message

Example Usage

# Check server status
piserver status

# View live logs
piserver logs

# Restart server
piserver restart

# Show auth token
piserver token

Example Status Output

  PiTunnel Server Status
  ────────────────────────────────────────
  Status:    ● Running
  PID:       12345
  Autostart: Enabled

  Configuration
  ────────────────────────────────────────
  Domain:    *.tunnel.example.com
  HTTP:      Port 80
  WebSocket: Port 8081
  API:       Port 8082

Configuration

Configuration file: /etc/pitunnel/config.json

{
  "domain": "tunnel.example.com",
  "httpPort": 80,
  "wsPort": 8081,
  "apiPort": 8082,
  "authToken": "your-secret-token-here"
}

Configuration Options

Parameter	Default	Description
domain	tunnel.example.com	Main domain for tunnel access
httpPort	80	Port for HTTP traffic
wsPort	8081	Port for WebSocket connections
apiPort	8082	Port for API endpoints
authToken	null	Client authentication token

Dynamic Port System

The server automatically starts listening on the client's target port. This enables Hot Module Replacement (HMR) for frameworks like React, Vite, and Next.js to work automatically.

Example:

• Client starts a tunnel with target 127.0.0.1:3000
• Server automatically starts listening on port 3000 as well
• Browser can request ws://tunnel-name.domain.com:3000/ws
• Server forwards this request to the client

Supported Ports:

• All user ports (1024+)
• 80 and 443 (HTTP/HTTPS)

Note: You may need to allow dynamic ports in your firewall.

API Reference

All API endpoints (except health) require authentication.

Authentication

Include one of the following headers with each request:

X-Auth-Token: your-token-here

or

Authorization: Bearer your-token-here

---

GET /health

Server health check. No token required.

Response:

{
  "status": "ok",
  "uptime": 3600,
  "tunnels": 5,
  "memory": {...},
  "domain": "tunnel.example.com"
}

---

GET /tunnels

Lists all active tunnels.

Response:

{
  "tunnels": [
    {
      "name": "my-tunnel",
      "target": "127.0.0.1:3000",
      "tunnelType": "web",
      "protocol": "http",
      "customDomain": null,
      "ports": [],
      "connectedAt": "2025-01-01T00:00:00.000Z",
      "uptime": 3600000,
      "stats": {
        "requests": 150,
        "bytesIn": 45000,
        "bytesOut": 1250000
      },
      "accessUrl": "http://my-tunnel.tunnel.example.com"
    }
  ],
  "count": 1
}

Note: If a tunnel has a custom domain configured, customDomain will contain the domain (e.g., "myapp.example.com") and accessUrl will be "http://myapp.example.com".

---

GET /tunnels/:name

Gets details of a specific tunnel.

Response:

{
  "name": "my-tunnel",
  "target": "127.0.0.1:3000",
  "tunnelType": "web",
  "protocol": "http",
  "connectedAt": "2025-01-01T00:00:00.000Z",
  "uptime": 3600000,
  "stats": {
    "requests": 150,
    "bytesIn": 45000,
    "bytesOut": 1250000
  },
  "accessUrl": "http://my-tunnel.tunnel.example.com"
}

---

DELETE /tunnels/:name

Stops a tunnel and closes the client connection.

Response:

{
  "success": true,
  "message": "Tunnel my-tunnel stopped"
}

---

POST /tunnels/:name/restart

Sends a restart command to the tunnel.

Response:

{
  "success": true,
  "message": "Restart command sent to my-tunnel"
}

---

GET /stats

Gets overall server statistics.

Response:

{
  "tunnels": 5,
  "totalRequests": 1500,
  "totalBytesIn": 450000,
  "totalBytesOut": 12500000,
  "uptime": 86400
}

---

Usage Examples

With cURL

# List tunnels
curl -H "X-Auth-Token: your-token" http://localhost:8082/tunnels

# Get specific tunnel info
curl -H "X-Auth-Token: your-token" http://localhost:8082/tunnels/my-tunnel

# Stop tunnel
curl -X DELETE -H "X-Auth-Token: your-token" http://localhost:8082/tunnels/my-tunnel

# Restart tunnel
curl -X POST -H "X-Auth-Token: your-token" http://localhost:8082/tunnels/my-tunnel/restart

# Get statistics
curl -H "X-Auth-Token: your-token" http://localhost:8082/stats

With JavaScript

const API_URL = 'http://localhost:8082';
const TOKEN = 'your-token';

// Get tunnel list
const response = await fetch(`${API_URL}/tunnels`, {
  headers: { 'X-Auth-Token': TOKEN }
});
const data = await response.json();
console.log(data.tunnels);

// Stop tunnel
await fetch(`${API_URL}/tunnels/my-tunnel`, {
  method: 'DELETE',
  headers: { 'X-Auth-Token': TOKEN }
});

With Python

import requests

API_URL = 'http://localhost:8082'
HEADERS = {'X-Auth-Token': 'your-token'}

# List tunnels
response = requests.get(f'{API_URL}/tunnels', headers=HEADERS)
tunnels = response.json()['tunnels']

# Stop tunnel
requests.delete(f'{API_URL}/tunnels/my-tunnel', headers=HEADERS)

DNS Configuration

Wildcard Subdomain (Default)

Create a wildcard DNS record for auto-generated subdomains:

*.tunnel.example.com  A  YOUR_SERVER_IP

Custom Domain Support

Clients can use their own custom domains. For this to work:

1. Client points their domain to your server IP:

   myapp.example.com    A    YOUR_SERVER_IP
   

2. Client starts tunnel with custom domain option:

   piclient start
   # Select "Custom domain" when prompted
   # Enter: myapp.example.com

3. The server automatically routes requests from myapp.example.com to the correct tunnel.

Note: Custom domains work alongside wildcard subdomains. You don't need any additional server configuration.

Firewall Configuration

Open the following ports:

# Basic ports
sudo ufw allow 80/tcp      # HTTP
sudo ufw allow 8081/tcp    # WebSocket
sudo ufw allow 8082/tcp    # API

# Dynamic ports (for HMR support)
sudo ufw allow 3000:9000/tcp   # Common development ports

Or to allow all ports:

sudo ufw disable
# or
sudo ufw default allow incoming

Nginx Reverse Proxy (Optional)

server {
    listen 80;
    server_name *.tunnel.example.com;

    location / {
        proxy_pass http://127.0.0.1:80;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Security

• Keep your token secure: Don't share your token with anyone
• Use HTTPS: SSL/TLS is recommended for production
• Firewall: Only open necessary ports
• API access: API endpoints are protected with token

License

MIT