Configuration

Device Agent configuration comes from three places: the console settings page, .device_agent/config.json, and startup environment variables or .env. For day-to-day changes, use the console settings page. For first startup, service deployment, and environment-specific values, use environment variables. For backup, migration, or bulk rollout, edit or replace the configuration file.

Configuration Sources

Source	Best for	Notes
Console settings page	Daily MQTT, model, voice, IM, and tool permission changes	Saves to .device_agent/config.json. The UI shows whether a restart is required.
.device_agent/config.json	Backup, migration, bulk rollout, or environments without UI access	Stores the main Device Agent runtime configuration.
Environment variables / .env	First startup, containers or system services, environment differences, secret injection	Read at startup. For config-backed fields, startup env values are written into the matching config file fields.

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	Stored in	Apply behavior
MQTT connection, topics, TLS	.device_agent/config.json, can be written by .env	Usually requires a gateway restart. Existing MQTT connections do not switch automatically.
Agent and vision models	.device_agent/config.json, can be written by .env	Saving in the console updates the running agent configuration.
Voice provider, models, and credentials	.device_agent/config.json, can be written by .env	Can update while the service is running; enable state, bind host, port, and TLS changes require restart.
IM channels	.device_agent/config.json, can be written by .env	Channels are loaded at startup, so changes require restart.
Tool permissions	.device_agent/config.json, with optional env overrides	Saving in the console updates runtime permissions. Env-overridden fields are shown as overridden in the UI.
Logging	.device_agent/config.json, can be written by .env	Saving updates log level and output behavior.
HTTP bind address, database, A2A identity, additional IM channels	.env	Read at startup only.
Web frontend variables	.env	Read by the frontend dev server or build process. Restart or rebuild the frontend after changing them.

If a field is set in both .env and the console, the .env value is written again on the next restart. To keep console changes long-term, remove the matching .env variable or keep both values aligned.

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=3000

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

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.