Installation

Install and start Device Agent, then 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 LLM 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 an MQTT Broker and an LLM service. Before installing, make sure you have:

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

Prepare an MQTT Broker

If you do not have an MQTT Broker yet, the fastest setup is to set ZERO_EMQX_ENABLED=true on first startup. Device Agent creates a temporary Zero EMQX Broker and writes the MQTT settings. The broker is powered by EMQX Cloud, expires automatically, and is not intended for long-term use. For other broker options, see MQTT Broker.

Prepare LLM Configuration

The quick start needs an LLM that supports tool calls. On first startup, set LLM_PROVIDER, LLM_MODEL, and the matching API key; you can also fill these values after startup from Settings → Models in the console. For more providers, fields, and local model options, see LLM Configuration.

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

For a first run, set startup variables directly before device-agent:

ZERO_EMQX_ENABLED=true \
LLM_PROVIDER=openai \
LLM_MODEL=gpt-5.5 \
OPENAI_API_KEY=sk-... \
device-agent

When using an existing MQTT Broker, replace ZERO_EMQX_ENABLED=true with MQTT_BROKER_URL, VITE_MQTT_WS_URL, MQTT_USERNAME, and MQTT_PASSWORD. For long-running deployments, use .env or config.json; see Environment Variables for paths and MQTT Broker for broker examples.

Start and Verify

If you did not start Device Agent in the previous step, run:

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. 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.