Configuration
Configure Device Agent from the console, .device_agent/config.json, or startup environment variables. Use the console for daily changes and configuration files or environment variables for deployment and bulk setup.
Configuration Sources
| Source | Best for |
|---|---|
| Console settings page | Daily MQTT, model, voice, channel, permission, and Webhook changes. |
.device_agent/config.json | Backup, migration, bulk rollout, or environments without UI access. |
Environment variables / .env | First startup, containers, system services, and secret injection. |
In development, .env is usually in the repository root. The installed binary reads .env from the install directory, not from an arbitrary shell working directory. Use the Runtime Home line in the startup logs as the source of truth for the configuration directory; in production it is usually ~/.device_agent.
Apply Behavior
| Configuration | Apply behavior |
|---|---|
| Agent model, vision model, tool permissions, logging, and Webhooks | Apply immediately after saving. |
| Voice provider, models, and credentials | Apply immediately after saving; enable state, bind address, port, or TLS changes require a restart. |
| MQTT | Reconnects immediately after saving in the console. Changes made in .env or the config file require a restart. |
| IM channels | Require a restart. |
| HTTP, HTTPS, database, and A2A identity | Require a restart. |
| Web frontend variables | Require a frontend restart or rebuild. |
If the same setting appears in both .env and the console, .env takes precedence at restart. Remove the matching environment variable to keep the console value.
Minimal Startup Example
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-5.5
OPENAI_API_KEY=sk-...
AGENT_GATEWAY_HTTP_HOST=127.0.0.1
AGENT_GATEWAY_HTTP_PORT=3000To access the console from a server IP or LAN address, set AGENT_GATEWAY_HTTP_HOST to 0.0.0.0 and adjust AGENT_GATEWAY_HTTP_PORT if needed.
For direct access on a trusted network, enable HTTPS. On a shared or untrusted network, also use an authenticated reverse proxy, VPN, or equivalent access control. See Installation.
Next
- Console settings are covered in Console Settings.
- MQTT Broker setup is covered in MQTT Broker.
- LLM and vision models are covered in LLM Configuration.
- Speech providers and the voice channel are covered in Voice Configuration.
- Configuration file structure is covered in Configuration File.
- Startup environment variables are covered in Environment Variables.