Connect Devices

IronFlock supports multiple ways to connect devices, depending on the hardware and operating system. No hardware at hand? You can simulate a device on your laptop in minutes.

Prerequisites

Before connecting a device, make sure you have:

1. A project created on IronFlock
2. A device entry created within that project (click NEW DEVICE in the project Settings -> Devices panel.)
3. The downloaded device configuration file (.flock)

Device on a restricted corporate network? Plan the network setup before installing — it is the most common reason a freshly installed device stays offline:

• Identity-aware firewall or proxy: the rule that admits the device must be bound to the device itself, never to a logged-in user — otherwise the device drops off the network whenever that user’s session lapses. See Identity-Aware Firewalls and Proxies.
• Corporate HTTP proxy: the agent and Docker must be told about it explicitly — see Behind a Corporate Proxy → Edge Devices.
• Connecting to an on-premises Appliance: the device must reach the appliance’s service ports directly — or, when the appliance runs HTTPS with your corporate certificate, only port 443, with your corporate root CA trusted on the device. See Device Connectivity in the Appliance guide.
• Clock drift: corporate firewalls usually block the public time servers a fresh operating system ships with, so the device clock silently drifts — configure your internal NTP server. See Time Synchronization (NTP).

Identity-Aware Firewalls and Proxies

Every edge device runs the IronFlock agent as an unattended system service. It starts at boot, stays connected around the clock and keeps installing apps, pulling images and updating itself — whether or not anyone is signed in on the device. That holds wherever your platform runs: in the IronFlock cloud, in your private cloud or on an on-premises appliance.

OT networks are increasingly protected by identity-aware firewalls and proxies, which grant access by directory identity instead of by network address. If the rule that admits an edge device is bound to the user who is logged in on it, the device loses the network whenever that user’s session lapses:

• Connections that are already open keep running, so the device still shows as online.
• Every new connection is silently dropped — app installs, image pulls, agent updates and reconnects fail.
• After the next restart of the agent or the device, it cannot reconnect at all and stays offline until someone signs in on the device again or the rule is changed.

Ask your network team to bind the rule to the device, never to a person:

How this maps to common products:

• Check Point Identity Awareness: in the Access Role, select the machine (computer object or group) instead of users. Machine identities are refreshed by the computer’s own domain activity; if they can lapse on your gateway, use a network object instead.
• Palo Alto Networks User-ID: computer accounts do not produce IP-to-user mappings, so use an address object, a tag or Device-ID.
• Fortinet FSSO and similar directory-based firewalls: use an address object for the device, or the dynamic address your network access control assigns.
• Zscaler, Prisma Access and other cloud security gateways: register the device network as an IoT or server location (a trusted source), so device traffic is identified by location rather than by user.

This is not an exemption from your identity policy — it identifies the device by the identity it actually has. If you run an on-premises appliance, the same applies to the appliance host: see Network Identity for IronFlock Hosts.

Recognizing the failure. A device that stays online while app installs, image pulls or agent updates fail with timeouts — and pings still succeed — points at an identity rule that has expired, not at the device. Don’t restart the agent or the device until a fresh connection from it succeeds again: the session that is still open is the only one that works, and it keeps the device manageable remotely in the meantime.

Test First: Simulate a Device on Your Laptop

You don’t need physical hardware to explore IronFlock. The FlockFlasher app can run the IronFlock agent directly on your laptop, so your laptop impersonates a real device within your project — perfect for testing apps and dashboards before rolling out to actual hardware.

1. Install Docker Desktop (or Docker Engine on Linux) and make sure it is running.
2. Download and install the FlockFlasher app for your OS.
3. Double-click the downloaded .flock file of your device — it opens in FlockFlasher and the device appears in the list. (Alternatively, open FlockFlasher and add the file via the + button.)
4. Click Test Device (▶) on the device entry. FlockFlasher automatically downloads the IronFlock agent on first use and starts it with your device configuration.

Your laptop now acts as this device within your IronFlock project: it appears online, and you can install and run apps on it exactly as on a real device. The apps run as Docker containers on your laptop.

When you are done, stop the test in FlockFlasher. You can later use the same .flock file to provision the real device — just make sure only one machine runs a given device configuration at a time.

Method 1: Flash an SD Card

Best for Raspberry Pi and other ARM devices that boot from SD cards.

1. Download the FlockFlasher app for your OS.
2. Insert an SD card (16 GB minimum) into your computer.
3. Open FlockFlasher and click the + button to load the .flock file.
4. Select the SD card drive (FlockFlasher auto-detects external drives).
5. Choose the correct image for your device (Raspberry Pi 3/4, Zero, etc.).
6. Optionally configure WiFi so the device can connect at its destination.
7. Click Flash and wait for writing, validation, and configuration to complete.
8. Insert the SD card into the device and power it on.

The device should come online within 20 minutes.

Warning: The flashing process erases all data on the selected drive. FlockFlasher hides internal drives by default, but always double-check your selection.

Method 2: USB Installer for Industrial PCs

For AMD64 devices with EFI boot (e.g., Siemens SIMATIC Box IPC).

1. Insert a USB stick (16 GB minimum) and open FlockFlasher.
2. Load the .flock file and select the USB drive.
3. Select the Industrial PC x86_64 (EFI) image.
4. Click Flash and wait for completion.
5. If necessary, change the boot order in the device’s BIOS to boot from USB.
6. Insert the USB stick and power on the device.

The device should come online within 60 minutes.

Method 3: Custom Installation

For devices keeping their existing Linux OS. Ideal for NVIDIA Jetson and custom hardware.

Note: This manual installation method is intended for real production hardware such as industrial PCs, gateways, and embedded devices — not for laptops. If you just want to try IronFlock on your laptop, follow Test First: Simulate a Device on Your Laptop instead — no manual agent installation required.

Linux / Unix Devices

1. SSH into the device.
2. Download the setup binary:

   curl -sSL https://instance-registry.ironflock.com/dl/reswarmify/install.sh | bash

   On an IronFlock appliance? Use the commands shown in the New Device dialog — they point at the appliance instead of instance-registry.ironflock.com.

3. Copy the .flock file from your computer to the device:

   scp mydevice.flock user@device-ip:/home/user/

4. Run the agent:

   sudo ./ironflock-init -c mydevice.flock

Behind a corporate proxy? Export your proxy before step 2 so the downloads succeed, and pass --http-proxy / --https-proxy to ironflock-init in step 4 so it configures the Docker engine for you. See Behind a Corporate Proxy for the full command and the corporate-CA steps.

Windows Devices

1. Install Docker Desktop on the device and enable Start Docker Desktop when you sign in in the Docker Desktop settings. For unattended devices, also configure Windows automatic sign-in so Docker is available after a reboot without anyone logging in.
2. Download reagent.exe.
3. Copy the .flock file to the device.
4. Install and start the agent as a Windows service from an elevated (Administrator) prompt:

   reagent.exe service install -config path\to\config.flock

   The service starts immediately and again at every boot, restarts automatically on failure, and keeps the agent up to date. Add -noStart to install without starting it, and check on it any time with reagent.exe service status.

Behind a corporate proxy? Add -proxy http://proxy.example.com:3128 to the service install command, and set Docker Desktop’s proxy under Settings → Resources → Proxies. See Behind a Corporate Proxy for details and the corporate-CA steps.

Windows device joined to your domain? The agent service runs as LocalSystem, with or without anyone signed in, so a firewall rule tied to the logged-in user does not cover it. Have the rule bound to the device’s computer account — see Identity-Aware Firewalls and Proxies.

Time Synchronization (NTP)

The device agent needs an accurate clock. The TLS handshake with the platform, the tokens that authorize image pulls and the timestamp on every data point the device publishes all depend on it. A device whose clock is more than 15 minutes out of step is also rejected by file storage with CLOCK_SKEW.

In a corporate network this is a setup step, not a given: outbound NTP on UDP port 123 is commonly blocked, so the public time servers the operating system ships with are unreachable and the clock drifts without any visible error. Ask your IT department for the internal time server and configure it on the device, or have them allow outbound UDP 123 for the device network.

Linux

With systemd-timesyncd (the default on Debian and Ubuntu):

sudo mkdir -p /etc/systemd/timesyncd.conf.d
sudo tee /etc/systemd/timesyncd.conf.d/corporate.conf > /dev/null <<'EOF'
[Time]
NTP=ntp.your-company.com
EOF
sudo systemctl restart systemd-timesyncd
timedatectl status

With chrony:

echo "server ntp.your-company.com iburst" | sudo tee -a /etc/chrony/chrony.conf
sudo systemctl restart chrony
chronyc sources

timedatectl status must report System clock synchronized: yes.

Windows

From an elevated (Administrator) prompt:

w32tm /config /manualpeerlist:"ntp.your-company.com" /syncfromflags:manual /update
w32tm /resync
w32tm /query /status

Devices flashed with a ready-made IronFlock image (Methods 1 and 2) synchronize from public time servers by default. On a network that blocks them, either allow outbound UDP 123 for the device subnet, or configure the internal time server over SSH after the first boot, exactly as shown for Linux above.

Verifying the Connection

After connecting, check the device status in your project:

• Green indicator — Device is online and communicating with IronFlock.
• Red indicator — Device is offline. Check the network connection and ensure the agent is running.
• Green, but app installs, image pulls or agent updates time out — a firewall rule may have stopped admitting new connections from the device. Read Identity-Aware Firewalls and Proxies before restarting anything.

The device map view shows the geographic location of all devices in the project.