# Configuration

Device Agent configuration comes from three places: the console settings page, `.device_agent/config.json`, and the workspace-root `.env`. For day-to-day changes, use the console settings page. For first startup, service deployment, and environment-specific values, use `.env`. 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. |
| `.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, the runtime home is usually `.device_agent` under the repository. In production, it is usually `~/.device_agent`. Use the `Runtime Home` line in the startup logs as the source of truth.

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

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

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](./configuration/settings-ui.md).
- Configuration file structure is covered in [Configuration File](./configuration/config-file.md).
- Startup environment variables are covered in [Environment Variables](./configuration/environment-variables.md).