How It Works

Architecture Overview

The Device Gateway sits between your physical devices and the Lua agent runtime. It handles authentication, connection management, command routing, and trigger delivery.

Self-Describing Flow

When a device connects, it does not need any server-side configuration. The device tells the gateway what it can do, and the gateway tells the agent.

Device connects with command manifest

The device client sends its commands array during the Socket.IO auth handshake or MQTT online status message. Each command includes a name, description, and optional JSON Schema for input parameters.

Gateway registers device

The gateway validates the device credential, its exact agent and device binding, and the permitted operations. It then registers the device and stores the permitted command manifest.

Agent discovers tools

When the agent processes a user message, it queries connected devices and merges their commands into the tool list. Each device command appears as a tool named device__{deviceName}__{commandName}.

Device disconnects, tools disappear

When a device goes offline (intentional disconnect, network loss, or missed heartbeats), its tools are removed from the agent. No stale tools remain.

Command Delivery Path

When the agent decides to use a device tool, the command flows through the gateway: Each command carries a unique commandId for idempotency. If the device receives the same command twice (due to retry or redelivery), it returns the cached response.

Trigger Flow

Triggers go in the opposite direction — from device to agent:

Triggers are fire-and-forget from the device’s perspective. The device gets an acknowledgment that the gateway received the trigger, but does not wait for the agent to finish processing it.

Transport Comparison

Feature	Socket.IO	MQTT
Protocol	WebSocket over HTTPS	MQTT 3.1.1 over TLS
Default URL	`https://api.heylua.ai`	`wss://mqtt.heylua.ai/mqtt`
Reconnection	Built-in with jitter	Built-in with backoff
Message ordering	Guaranteed (single socket)	Guaranteed per topic (QoS 1)
Offline queueing	No	Yes (persistent session)
Last Will (LWT)	Not applicable	Automatic offline status on disconnect
Best for	Node.js, desktops, servers	Microcontrollers, battery devices, flaky networks
RAM footprint	~10 MB (Node.js)	~30 KB (MicroPython on Pico W)

Security Model

Bound device credentials

New installations use a credential bound to one agent, one device name, and selected device operations. Existing non-dotted legacy keys remain supported indefinitely.

Agent Scoping

A device can only interact with the agent it authenticates against. Cross-agent communication is not possible.

TLS Encryption

All transports use TLS. Socket.IO connects over HTTPS. MQTT connects over port 443 (WebSocket) with TLS.

Heartbeat Monitoring

The gateway expects a heartbeat every 30 seconds. Missed heartbeats trigger disconnect detection. MQTT additionally uses Last Will and Testament (LWT) for instant offline notification.

Connection Lifecycle

Socket.IO
MQTT

Client opens WebSocket to https://api.heylua.ai/devices
Auth handshake: { apiKey: deviceCredential, agentId, deviceName, commands[] }
Server validates the credential binding and permitted operations, then emits 'connected'
Client starts heartbeat (every 30s)
Bidirectional command/trigger exchange
On disconnect: auto-reconnect with jittered exponential backoff
On reconnect: re-sends auth (commands may have changed)
On SIGTERM/SIGINT: graceful disconnect, no reconnect

Client connects to wss://mqtt.heylua.ai/mqtt
   - username: {agentId}:{deviceName}
   - password: {deviceCredential}
   - LWT: offline status (retained)
Client subscribes to: command, connected, trigger_ack, error
Client publishes online status (retained, no secrets)
Client publishes commands without the typed credential (non-retained)
Client starts heartbeat (every 30s)
Bidirectional command/trigger exchange via topics
On disconnect: broker publishes LWT, server detects offline
On reconnect: re-subscribe, re-publish online status

The Socket.IO auth.apiKey property and MQTT password remain the protocol fields for both device credentials and existing legacy keys. The Node.js client uses deviceCredential for new provisioning. Published Python and MicroPython clients continue to use api_key with existing legacy keys. See Device credentials.

Next Steps

Self-Describing Commands

Deep dive into how devices declare their capabilities

Triggers

Understand device-to-agent event flow

MQTT Transport

Configure MQTT for constrained devices

Agent Tools

How device commands become agent tools

Getting Started

Device Client

Agent Integration

Examples

Advanced

CLI Commands

Architecture Overview

Self-Describing Flow

Command Delivery Path

Trigger Flow

Transport Comparison

Security Model

Bound device credentials

Agent Scoping

TLS Encryption

Heartbeat Monitoring

Connection Lifecycle

Next Steps

Self-Describing Commands

Triggers

MQTT Transport

Agent Tools

​Architecture Overview

​Self-Describing Flow

​Command Delivery Path

​Trigger Flow

​Transport Comparison

​Security Model

Bound device credentials

Agent Scoping

TLS Encryption

Heartbeat Monitoring

​Connection Lifecycle

​Next Steps

Self-Describing Commands

Triggers

MQTT Transport

Agent Tools

Architecture Overview

Self-Describing Flow

Command Delivery Path

Trigger Flow

Transport Comparison

Security Model

Connection Lifecycle

Next Steps