How to Run an AI IoT & MQTT Agent with OE Runtime

Subscribe to sensor feeds and publish commands to IoT devices via MQTT. OE Runtime lets you run a local AI agent that monitors device data, evaluates thresholds, and publishes automated responses — no IoT platform subscription required.

What You Need

• Node.js 18+ installed, or the OE Runtime binary from openenthrium.com/runtime
• An API key from OpenAI, Anthropic, or any supported LLM provider
• An MQTT broker — local Mosquitto or a cloud broker like HiveMQ (free tier available)
• A text editor — nothing else

Create the Project Folder

Create a folder called iot-messaging/ and add these two files:

The Skill Files

Create SKILL.md inside an iot-messaging/ directory. This is the portable skill — it follows the agentskills.io format and runs unchanged on Claude, Cursor, Windsurf, or OE Runtime:

---
name: iot-messaging
description: Publish commands and read sensor data via MQTT
license: Apache-2.0
metadata:
  author: Open Enthrium
  version: "1.0"
---

You are an IoT agent. Subscribe to sensor data feeds and publish commands to devices via MQTT.
Format all messages as JSON. Always read current state before publishing any commands.
Complete all steps fully before writing your report.

## Step 1: Read Sensor Data
Subscribe to the sensor data topic and read the latest 5 messages.
Extract: device ID, sensor type, value, unit, and timestamp for each message.

## Step 2: Evaluate and Publish Command
Analyze the sensor readings:
- If any temperature reading exceeds 30°C, publish a cooling command to the control topic
- If any humidity reading exceeds 80%, publish a ventilation command
- Otherwise publish a status check ping to the control topic
All commands must be JSON with fields: action, device_id, timestamp, triggered_by.

## Step 3: Report
Summarize IoT activity:
- Sensor readings received (device, value, unit)
- Any threshold breaches detected
- Commands published (topic, payload)
- Current system status (normal / alert)

Create agent.yaml in the same directory to wire the skill to your connector:

name: IoT Agent
description: Publish commands and read sensor data via MQTT
connectors:
  - connection_name: MQTT Broker
    connection_type: mqtt
skills:
  - path: ./
    trigger_type: auto

The Config File

Create oe-config.json in the same directory:

{
  "llm": {
    "provider": "openai",
    "model": "gpt-4o",
    "apiKey": "YOUR_OPENAI_API_KEY"
  },
  "server": {
    "enabled": false,
    "port": 3333,
    "apiKey": "your-secret-api-key"
  },
  "connectors": [
    {
      "connection_name": "MQTT Broker",
      "connection_type": "mqtt",
      "broker": "mqtt://localhost:1883",
      "clientId": "oe-runtime",
      "topic": "devices/#",
      "username": "YOUR_MQTT_USER",
      "password": "YOUR_MQTT_PASSWORD"
    }
  ]
}

Replace the broker URL with your MQTT broker address. This works with any MQTT broker including Mosquitto, HiveMQ, AWS IoT Core, and Azure IoT Hub. Remove username/password fields if your broker does not require authentication.

Download OE Runtime

Run the Agent

From the parent folder containing your skill directory:

1 npx recommended

npx -y @openenthrium/oe-runtime@latest ./iot-messaging

2 Windows

oe-runtime-win.exe ./iot-messaging

3 macOS

chmod +x oe-runtime-macos
./oe-runtime-macos ./iot-messaging

First run blocked? System Settings → Privacy & Security → Allow Anyway.

4 Linux

chmod +x oe-runtime-linux
./oe-runtime-linux ./iot-messaging

5 API Server integration

Add a "server" block to oe-config.json, then start with --serve:

{
  "llm": { ... },
  "server": { "enabled": true, "port": 3333, "apiKey": "your-secret-key" },
  "connectors": [ ... ]
}

npx -y @openenthrium/oe-runtime@latest --serve --config oe-config.json

Run with inline YAML:

curl -X POST http://localhost:3333/run \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-key" \
  -d '{"yaml": "...", "params": {}}'

Or run from a file on the server:

curl -X POST http://localhost:3333/run-file \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-key" \
  -d '{"file": "/path/to/agent.yaml", "params": {}}'

Use Cases

• Temperature and environment monitoring — Subscribe to temperature, humidity, and CO2 sensor feeds from smart building devices and automatically trigger ventilation, cooling, or heating commands when thresholds are breached. The agent evaluates multiple sensors simultaneously and publishes the appropriate response command without any manual intervention.
• Industrial equipment monitoring — Monitor vibration, pressure, and temperature sensors on manufacturing equipment and publish alerts or shutdown commands when readings indicate potential failure. Early detection of anomalies reduces unplanned downtime and extends equipment lifespan.
• Smart agriculture automation — Read soil moisture, light intensity, and nutrient level sensors across a field and publish irrigation or lighting commands to connected actuators based on crop requirements. The agent can be configured with crop-specific thresholds for different zones of the farm.
• Energy management — Subscribe to smart meter and sub-meter data to monitor real-time energy consumption across facilities. Publish load-shedding commands to non-critical devices when consumption exceeds a set threshold to reduce peak demand charges.
• Warehouse and cold chain monitoring — Monitor temperature and humidity in cold storage facilities and publish alerts when conditions drift outside safe ranges for stored goods. For pharmaceutical or food cold chains, the agent can also log readings to an audit trail for compliance purposes.
• Fleet and asset tracking — Subscribe to GPS and telemetry data published by vehicles or mobile assets and generate position reports or geofence alerts. The agent can identify when an asset leaves a defined zone and publish a notification command to the fleet management system.
• Security and access control — Read motion sensor, door contact, and access reader events via MQTT and publish lock, alarm, or notification commands based on the detected activity. The agent can apply time-based rules — for example, flagging motion detected outside business hours.
• Predictive maintenance scheduling — Analyse patterns in sensor data over time to identify equipment that is trending towards a failure threshold. The agent publishes a maintenance request event to the MQTT topic monitored by your work order management system before failure occurs.