Installation

This page explains how to download, install, and start Device Agent. After installation, open the Web console to create device agents and connect MQTT devices.

Where to Install

Device Agent supports macOS, Linux, and Windows. You can install it on a development computer, edge gateway, Linux industrial computer, or private server. The environment needs access to your MQTT Broker and model service, and the Web console port must be reachable. The default port is 3000.

• Local evaluation: install it on your development computer and open http://127.0.0.1:3000.
• On-site runtime: install it on an edge gateway, Linux industrial computer, or private server close to the device network, then access the console from the server IP.

Recommended Hardware

Setup	CPU	Memory	Disk	Best for
Minimum	2 cores	512 MB	300 MB free	Local evaluation, demos, and small board deployments
Recommended	2-4+ cores	1 GB+	1 GB free	Long-running on-site runtime

Prerequisites

Device Agent connects to your existing MQTT Broker and model service. Before installing, make sure you have:

• MQTT Broker endpoint and credentials
• Model provider, model name, and API key
• Browser access to the Device Agent Web console port, 3000 by default

If you do not have an MQTT Broker yet, the fastest setup is to ask an Agent to create Zero EMQX MQTT Broker. It creates a temporary Zero EMQX test broker and writes the MQTTS/WSS endpoints and credentials into the current configuration. The broker instance is powered by EMQX Cloud. Tell the Agent:

Create a Zero EMQX MQTT Broker test instance and write the MQTT settings into this workspace.

After the Agent finishes, save Settings > MQTT to apply the configuration. You can also click Create test broker on the MQTT settings page, or create one from shell:

curl -sS -X POST https://zero.emqx.io/v1/instances

The response includes mqtts.uri, wss.uri, credentials.username, and credentials.password. For the ready-to-copy .env command and EMQX, EMQX Cloud, or EMQX Edge options, see MQTT Broker.

Download and Install

macOS and Linux

curl -fsSL https://emqx.sh/device-agent | sh
device-agent --version

Windows PowerShell

irm https://emqx.sh/device-agent.ps1 | iex
device-agent --version

Configure

At startup, Device Agent reads a .env file to connect to MQTT and the model service, and to set or override default configuration. Create one in the runtime directory. Use the values from your broker setup, or see MQTT Broker for Zero EMQX, EMQX, EMQX Cloud, and EMQX Edge examples:

MQTT_BROKER_URL=mqtt://broker.example.com:1883
MQTT_USERNAME=your-username
MQTT_PASSWORD=your-password
VITE_MQTT_WS_URL=wss://broker.example.com:8084/mqtt

LLM_PROVIDER=openai
LLM_MODEL=gpt-4.1
OPENAI_API_KEY=sk-...

After startup, you can also update MQTT, model, voice, and external access settings from the console settings page, or edit .device_agent/config.json in the user directory. See Configuration for details.

Start and Verify

Start Device Agent:

device-agent

Then open the Web console:

http://127.0.0.1:3000

To access the Web console from a server IP or LAN address, set the HTTP host in .env. 3000 is the default port; replace it only when you need a different port:

AGENT_GATEWAY_HTTP_HOST=0.0.0.0
AGENT_GATEWAY_HTTP_PORT=3000

If you can enter the device agent creation flow and the MQTT connection is healthy, the installation is ready.

Update

macOS, Linux, and Windows:

device-agent update

Restart Device Agent after updating.

Uninstall Device Agent

Stop Device Agent first.

macOS and Linux

Remove the install directory and launcher:

rm -rf "${XDG_DATA_HOME:-$HOME/.local/share}/device-agent"
rm -f ~/.local/bin/device-agent

To also remove runtime config and local data:

rm -rf ~/.device_agent

For custom installs: remove the install directory set by DEVICE_AGENT_INSTALL_DIR and the device-agent launcher under DEVICE_AGENT_BIN_DIR.

Windows PowerShell

Remove the install directory and launcher:

$root = Join-Path $env:LOCALAPPDATA "Programs\DeviceAgent"
Remove-Item -LiteralPath $root -Recurse -Force

To also remove runtime config and local data:

Remove-Item -LiteralPath (Join-Path $HOME ".device_agent") -Recurse -Force

For custom installs: remove the install directory set by DEVICE_AGENT_INSTALL_DIR and the device-agent.cmd launcher under DEVICE_AGENT_BIN_DIR.

Next Steps

• Read Quick Start to complete your first device agent experience.
• Go to Define a Device Agent to define device intelligence in natural language.
• See MQTT Access to connect real devices to Device Agent.