Configuring Ports

Define which services your app exposes for remote access by creating a port-template.yml file in the .ironflock/ directory.

Basic Example


ports:
  - name: Web Interface
    port: 5000
    main: true
    protocol: https

This makes port 5000 available for remote access. Users can enable the tunnel from the app settings on their device.

Full Example


ports:
  - name: Web Interface
    port: 1100
    main: true
    protocol: http
 
  - name: Video Stream
    port: 1200
    protocol: http
 
  - name: Remote Desktop
    port: 5900
    protocol: tcp
 
  - name: LoRaWAN Gateway
    port: 1700
    protocol: udp

Field Reference

Field	Required	Description
`name`	Yes	Label shown in the device’s app settings
`port`	Yes	Local port number the service listens on
`main`	No	If `true`, this port is used for the quick-access icon on the device’s app list
`protocol`	No	`http` (default), `https`, `tcp`, or `udp`

Injected Environment Variables

For every port you declare, the platform injects environment variables into your app’s containers so your code can discover where the service is actually reachable — without hardcoding addresses:

Variable	Description
`DEVICE_LAN_IP`	The device’s IP address on the local network
`DEVICE_PORT_FOR_<port>`	The port on the device where your declared port is published on the local network
`REMOTE_PORT_FOR_<port>`	The public port allocated by the tunnel server while the tunnel is active (TCP and UDP)
`REMOTE_PORT_FOR_<port>_CLOUD`	The internet-facing port when the device runs on an IronFlock instance that forwards tunnels through the cloud (TCP and UDP)

<port> is the port number you declared in port-template.yml. For the Remote Desktop example above, the app would receive DEVICE_PORT_FOR_5900 and — while its tunnel is active — REMOTE_PORT_FOR_5900.

Apps may run concurrently on the same device, so declared ports are mapped to a free port on the device automatically. Always compose local-network addresses from the injected values instead of assuming the declared port:


import os
 
lan_ip = os.environ.get("DEVICE_LAN_IP")
lan_port = os.environ.get("DEVICE_PORT_FOR_5900")
# service is reachable on the local network at {lan_ip}:{lan_port}

The variables are set when the container starts. Tunnel ports can change while the app is running (for example when a tunnel reconnects), so the current values are additionally kept up to date as files under /data/env/<VARIABLE_NAME>.txt — the IronFlock SDKs read these automatically.

How Protocols Work

HTTP / HTTPS

For web-based services. IronFlock creates a public URL that proxies traffic to the device’s local port. Users open the URL in their browser.

TCP

For protocols like VNC (Remote Desktop) or direct socket connections. IronFlock allocates a remote port on the tunnel server and exposes it to your app as REMOTE_PORT_FOR_<port>.

UDP

For protocols like LoRaWAN communication or VPN tunnels. Similar to TCP — a remote port is allocated and exposed as REMOTE_PORT_FOR_<port>.

Embedding in Boards

You can embed a device’s remote access tunnel directly into a board using the Embed Widget. This creates a seamless experience where users can:

Monitor global data from all devices
Interact with individual devices through embedded web UIs

All within the same dashboard.

Configuring remote access in port-template.yml does not automatically activate tunnels. Only privileged users can enable or disable tunnels on their devices.