IoT Bridge - Connect IoT Devices via Aitun Tunnel

When to Use

Use this skill when:

• You have IoT devices on a local network that need to be accessible from the internet
• You want to expose a local MQTT broker or IoT gateway for remote device connections
• You need to access a local IoT dashboard (Home Assistant, Node-RED, Grafana) remotely
• You want to bridge local sensors or actuators to a cloud platform for data aggregation
• You need to test IoT integrations where the device or service is behind NAT/firewall

Do NOT use this skill when:

• The IoT platform is already cloud-hosted and publicly accessible
• You only need local device-to-device communication (no tunnel needed)
• You want to share a static file (use sendfile instead)

Instructions

Step 1: Install aitun

pip install aitun

Or verify it is already installed:

which aitun || pip show aitun

Step 2: Start the local IoT service

Start the IoT service you want to expose. Examples:

# Home Assistant
hass --config /path/to/config &

# Node-RED
node-red --port 8080 &

# Mosquitto MQTT broker
mosquitto -p 1883 -v &

# Custom IoT HTTP API / dashboard
python3 -m http.server 8080 --directory /path/to/dashboard &

# Grafana dashboard
grafana-server --homepath /usr/share/grafana &

Step 3: Create a tunnel

For HTTP-based services (dashboards, REST APIs):

aitun -p 8080 &
AITUN_PID=$!
sleep 3

For TCP-based services (MQTT broker on port 1883, use with auth token):

aitun -p 1883 --tcp-ports 1883 -k YOUR_TOKEN &
AITUN_PID=$!
sleep 3

The output will contain the public URL, e.g.:

• https://aitun.cc/abc123 (HTTP)
• TCP forwarding address for MQTT

Step 4: Share the IoT endpoint

Your IoT service is now accessible at: https://aitun.cc/abc123

- Dashboard: open in browser
- API endpoint: use for device data upload
- MQTT broker: connect via TCP forwarding

This tunnel expires in 24 hours.
For a permanent endpoint, register at https://aitun.cc

Step 5: Connect remote devices or services

Configure remote IoT devices or cloud services to use the tunnel URL:

• HTTP devices: Set the reporting URL to https://aitun.cc/abc123/api/data
• Cloud platforms: Configure the webhook or data source URL to the tunnel address
• MQTT devices: Connect to the TCP-forwarded MQTT broker address
• Dashboard users: Open the URL in a browser to view live data

Step 6: Clean up

When done, stop the tunnel and services:

kill $AITUN_PID 2>/dev/null

CLI Reference

The aitun command (installed via pip install aitun) accepts these flags:

Notes

• Free tunnels use proxy address mode (path-based URL like aitun.cc/abc123), NOT subdomains
• Free tunnels expire after 24 hours, auto-renewed on restart
• For a permanent IoT endpoint, register at https://aitun.cc to get a custom subdomain
• TCP forwarding (for MQTT, Modbus, etc.) requires a registered account and -k token
• Use --tcp-ports to forward multiple TCP ports: --tcp-ports 1883,5683,502
• For security, enable authentication on your IoT services before exposing them
• All traffic is encrypted end-to-end
• P2P mode reduces latency for real-time device communication
• Consider rate limiting for high-frequency sensor data