Configuration
Device Agent provides global settings and configuration for each device agent. Global settings maintain model and speech services, IoT platform connections, channels, and tool permissions. Individual agent settings maintain roles, timezones, recognition vocabulary, voice tool scope, and responses.
Configuration Sources
| What to change | Entry |
|---|---|
| Model provider, reasoning effort, vision, or speech services | Settings → Models; see Console Settings. |
| IoT platform, MQTT, channels, tool permissions, or Webhook | The corresponding entry under Settings. |
| One agent's prompt, timezone, vocabulary, voice tools, identity replies, or wait messages | Agent card More → Configuration overview; see Device Agent Configuration. |
| Platform device AI credits or request authorization | Settings → AI Credits / License. |
Global model settings provide the AI model service. A device model describes properties, actions, and events. Use configuration overview to adjust prompts and responses; use the modeling entry in Define a Device Agent to change device capabilities.
| Source | Best for |
|---|---|
| Console settings page | View the IoT provider, MQTT, and models; adjust voice, channels, tool permissions, and Webhooks. The platform also provides AI Credits and License settings. |
.device_agent/config.json | Local backup, migration, bulk deployment, or configuration without UI access. Maintain platform settings through the console or deployment administrator. |
Environment variables / .env | First startup, containers, system services, bind addresses, and secret injection. |
In local development, .env is usually in the repository root. The installed binary reads .env from the install directory. Check Runtime Home in the startup logs for the configuration directory; in production it is usually ~/.device_agent. The deployment administrator maintains initial platform settings and credentials. See Platform Deployment.
Apply Behavior
| Configuration | Local runtime | Platform deployment |
|---|---|---|
| Agent and vision models | Apply immediately after saving in the console. | Read-only in the console; contact the deployment administrator for changes. |
| Individual agent configuration | Used by subsequent requests after saving; vocabulary applies on the next voice connection. | Same as local. See configuration overview for editable fields. |
| Tool permissions and Webhooks | Apply after saving. | Apply after saving. Tool permissions restrict agent tools; they are not user role permissions. |
| Voice provider, models, and voices | Apply after saving; enable state, bind address, port, or TLS changes require a restart. | Non-secret parameters are editable and apply after the relevant services restart. Credential fields show configuration status only. |
| MQTT | Reconnects after saving in the console. Changes made in .env or the config file require a restart. | Regular settings are read-only in the console. Platform services manage the connection. |
| IM channels | Require a restart after saving. | Non-secret settings such as enabled state, identifiers, and allowed sources are editable and apply after the relevant services restart. |
| HTTP, HTTPS, database, A2A identity, and deployment credentials | Require a restart. | Restart affected services after updating deployment settings. |
| Web frontend variables | Require a frontend restart or rebuild. | Require a frontend restart or rebuild. |
After saving, follow the status notice. Complete a restart when required, then confirm that connections and conversations work. See Monitoring for platform status.
In a local runtime, matching .env variables override console settings at every startup. Remove those variables to retain console values. Use the platform console for daily changes; contact the deployment administrator to change model services or credentials.
Minimal Startup Example
This example is for a local runtime. For platform services and PostgreSQL settings, see Platform Deployment.
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.
- See LLM Configuration for the primary model and Vision Configuration for vision models.
- 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.
- Device consumption limits are covered in AI Credits; platform request quotas and validity are covered in License.