Edge Device & IoT Fleet Management

Managing cloud servers in a data center is straightforward because they have static IP addresses and reliable gigabit fiber links. Managing distributed edge compute nodes—such as ARM64 Raspberry Pi kiosks, retail point-of-sale appliances, factory gateways, or cellular-connected field devices—introduces physical-world networking challenges:

1. Strict Inbound NAT & Dynamic IP Addresses: Edge devices sit behind retail, restaurant, or cellular NAT routers where inbound Port 22 (SSH) is completely unreachable.
2. Broken ISP IPv6 Routing: Consumer and retail routers frequently advertise incomplete IPv6 routes that cause 10-second connection timeouts.
3. Aggressive Cellular / SIM NAT Drops: 4G/LTE and 5G carrier gateways silently drop idle TCP connections after 15–30 seconds without sending a TCP RST packet.

The RasnuOS Agent (rasnuos-agent-linux-arm64 and rasnuos-agent-linux-amd64) is engineered to survive these exact conditions out of the box.

Rendering diagram…

---

How the Agent Handles Unstable Edge Networks

Edge Network Constraint	How the RasnuOS Agent Solves It	Operational Impact
No Public IP / Strict NAT Firewall	Dials outbound only over TCP port 443 (WSS and HTTPS) as soon as the device boots	Zero router port-forwarding, VPN client configuration, or static IP leases required
Cellular / 4G / 5G NAT Idle Drops	Enforces a 5-second HTTP idle connection timeout (IdleConnTimeout = 5s)	Periodic metrics and heartbeat calls always use a fresh socket rather than hanging on a dead carrier NAT mapping
Misconfigured ISP Dual-Stack IPv6	Forces IPv4 (tcp4) socket dialing on all outgoing agent requests	Eliminates 10-second AAAA DNS lookup and connection timeouts on retail broadband links
Half-Open Zombie TCP Sockets	Sets a 10-second write deadline, a 60-second pong read deadline, and forces a clean reconnect after 3 failed pings or 3 failed HTTP heartbeats	Detects silent network blackholes within seconds and re-establishes the command channel automatically
Post-Outage Reconnection Storms	Uses exponential backoff (1s doubling to 60s) with up to 50% random jitter	Prevents thousands of kiosks from hammering the network simultaneously when regional power or cell service returns

---

Scenario 1: Zero-Touch ARM64 Digital Signage & Kiosk Updates

The Challenge

You manage 500 Raspberry Pi 5 (linux/arm64) digital menu boards installed in fast-food restaurants across the country. Every device sits behind the restaurant's private NAT firewall, and Wi-Fi signal strength varies by location. You need to deploy release v2.4.1 of your Node.js/Electron kiosk application and restart the kiosk-ui.service daemon without leaving any kiosk in a half-updated state if its connection drops mid-download.

Step 1: Outbound-Only Registration

Each Raspberry Pi runs rasnuos-agent-linux-arm64 managed by systemd (Restart=always, RestartSec=10). The moment a staff member plugs in the Raspberry Pi, it connects outbound over port 443 and joins the Restaurant Kiosks Server Group.

Step 2: Atomic Symlink Rollout Across the Fleet

Open a conversation targeting the Restaurant Kiosks Server Group and prompt:

"Download release v2.4.1 of kiosk-linux-arm64.tar.gz with resume retries, verify its SHA-256 checksum, extract it into /opt/kiosk/releases/v2.4.1, atomically flip the /opt/kiosk/current symlink, and restart kiosk-ui.service."

RasnuOS executes an atomic staging script so the active /opt/kiosk/current directory is never modified until the entire archive is downloaded and cryptographically verified on disk:

set -euo pipefail

RELEASE="v2.4.1"
EXPECTED_SHA256="4a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b"
STAGE_DIR="/opt/kiosk/releases/${RELEASE}"
TMP_TAR="/tmp/kiosk-${RELEASE}.tar.gz"

mkdir -p /opt/kiosk/releases

# 1. Resume-capable download (-C -) with automatic retries for spotty 4G/Wi-Fi links
curl -fL --retry 5 --retry-delay 3 -C - \
  -o "${TMP_TAR}" "https://releases.example.com/kiosk/${RELEASE}/kiosk-linux-arm64.tar.gz"

# 2. Verify SHA-256 digest before extracting (aborts immediately if corrupted)
echo "${EXPECTED_SHA256}  ${TMP_TAR}" | sha256sum -c -

# 3. Extract into isolated release directory and atomically swap symlink
mkdir -p "${STAGE_DIR}"
tar -xzf "${TMP_TAR}" -C "${STAGE_DIR}"
rm -f "${TMP_TAR}"
ln -sfn "${STAGE_DIR}" /opt/kiosk/current

# 4. Restart kiosk daemon and confirm active state
systemctl restart kiosk-ui.service
systemctl is-active --quiet kiosk-ui.service

Instant Symlink Rollback

If the new UI release exhibits a bug in production, triggering the step's rollback immediately points /opt/kiosk/current back to the previous release directory already on disk—requiring zero network bandwidth:

PREV_RELEASE=$(ls -1dt /opt/kiosk/releases/* | sed -n '2p')
if [ -n "$PREV_RELEASE" ]; then
  ln -sfn "$PREV_RELEASE" /opt/kiosk/current
  systemctl restart kiosk-ui.service
fi

---

Scenario 2: Fail-Closed Over-The-Air (OTA) Agent Upgrades

When upgrading the rasnuos-agent binary itself on remote field devices (ExecuteSelfUpdate), a dropped 4G connection must never corrupt the agent executable or brick the device. The agent enforces a four-step Fail-Closed Update Pipeline:

1. Isolated Temporary Download: Downloads the new binary to a temporary path (rasnuos-agent.tmp) using a dedicated 240-second updater timeout.
2. Ed25519 Cryptographic Signature Verification: Verifies the detached 64-byte Ed25519 signature against the public key compiled into the binary (rasnuos-agent --key-info). If a single byte was corrupted during download or the signature does not match, the temporary file is deleted immediately and the running agent remains untouched.
3. Architecture Sanity Check: Runs the verified temporary binary with --version to confirm the binary executes cleanly on the host's CPU architecture and kernel.
4. Atomic Rename & Service Restart: Atomically replaces the binary on disk (mv / os.Rename) and restarts the rasnuos-agent service.

---

Scenario 3: SPKI TLS Certificate Pinning on Untrusted Public Networks

Edge kiosks deployed in shopping malls, airports, or third-party retail stores often connect through untrusted third-party routers that may attempt TLS interception. To guarantee that the agent only communicates with your authentic Control Plane, start the agent with Subject Public Key Info (SPKI) SHA-256 Pinning (--tls-pin):

/usr/local/bin/rasnuos-agent \
  --ws-url="wss://os.rasnu.com/app/rasnu-key" \
  --api-url="https://os.rasnu.com/api" \
  --token="${AGENT_TOKEN}" \
  --server-id="${SERVER_ID}" \
  --tls-pin="sha256//YhKJKSzoTt2b5FP18fvpHo7fJYqQCjAa3HWY3tvRMwE="

On every WebSocket and HTTPS handshake, the agent hashes the server certificate's RawSubjectPublicKeyInfo with SHA-256. If the fingerprint does not match --tls-pin, the TLS connection is terminated before the authentication token is ever transmitted.

---

Scenario 4: Remote Display Verification on Kiosks ([COMPUTER_INTENT])

On a digital menu board or interactive kiosk, confirming that kiosk-ui.service is active (running) does not always prove the physical screen is displaying properly (for example, if the browser is stuck on a blank screen or modal dialog).

RasnuOS supports remote GUI screenshot capture and input actions on hosts with an active display server:

[COMPUTER_INTENT] {"action": "screenshot", "coordinate": [0, 0], "text": ""}

The agent captures the live display framebuffer, Base64-encodes the image, and streams it over the WebSocket in paced 8 KB chunks so it renders directly inside your conversation timeline without saturating low-bandwidth cellular links.

---

Scenario 5: Protecting MicroSD & eMMC Flash Storage on Edge Nodes

Raspberry Pis and industrial IoT gateways often boot from MicroSD cards or soldered eMMC flash modules that wear out prematurely if subjected to excessive disk writes. You can use a RasnuOS Playbook across your Edge Fleet Server Group to cap systemd-journald disk usage, mount /tmp in RAM (tmpfs), and inspect flash wear indicators (mmcblk0 lifetime estimation):

set -euo pipefail

# 1. Cap systemd journal storage in RAM/volatile storage to prevent SD card wear
mkdir -p /etc/systemd/journald.conf.d
cat << 'EOF' > /etc/systemd/journald.conf.d/edge-flash.conf
[Journal]
Storage=volatile
RuntimeMaxUse=64M
EOF
systemctl restart systemd-journald

# 2. Check eMMC hardware life-time estimation registers if available
if [ -r /sys/block/mmcblk0/device/life_time ]; then
  echo "eMMC Wear Level (Hex): $(cat /sys/block/mmcblk0/device/life_time)"
  echo "eMMC Pre-EOL Info    : $(cat /sys/block/mmcblk0/device/pre_eol_info)"
fi

# 3. Verify root filesystem read/write state and available inodes
grep -E '\s/\s' /proc/mounts
df -h / /tmp