# 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](https://www.emqx.com/en/cloud). Tell the Agent:

```text
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:

```bash
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](./mqtt-broker.md).

## Download and Install

### macOS and Linux

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

### Windows PowerShell

```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](./mqtt-broker.md) for Zero EMQX, EMQX, EMQX Cloud, and EMQX Edge examples:

```bash
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](./operate-reference/configuration.md) for details.

## Start and Verify

Start Device Agent:

```bash
device-agent
```

Then open the Web console:

```text
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:

```bash
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:

```bash
device-agent update
```

Restart Device Agent after updating.

## Uninstall Device Agent

Stop Device Agent first.

### macOS and Linux

Remove the install directory and launcher:

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

To also remove runtime config and local data:

```bash
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:

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

To also remove runtime config and local data:

```powershell
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](./quick-start/quick-start.md) to complete your first device agent experience.
- Go to [Define a Device Agent](./usage/create-agent.md) to define device intelligence in natural language.
- See [MQTT Access](./device-access/mqtt.md) to connect real devices to Device Agent.