Configuration File

.device_agent/config.json is the configuration file for a local Device Agent runtime. Values saved from the console, including the IoT provider, MQTT, models, voice, IM, logging, and tool permissions, are written to this file. If the file does not exist, Device Agent creates it at startup from defaults and startup values in .env.

File Location

The local runtime home depends on how Device Agent is started:

Runtime	Common Location
Development	<repo>/.device_agent/config.json
Production	~/.device_agent/config.json

Use the Runtime Home path shown in the startup logs. Uploaded certificates, log files, user skills, and tool extensions are also stored under this runtime home.

Platform deployments use shared configuration in PostgreSQL. All runtime services read the same saved values, and deployment credentials are injected at startup. Platform console changes do not write a local config.json; copying or deleting this file does not migrate or reset platform configuration. See Platform Operations for configuration and data backups, and Platform Deployment for deployment parameters.

File Structure

The configuration file contains these top-level fields:

{
  "version": 1,
  "iotPlatform": {},
  "mqtt": {},
  "models": {},
  "voice": {},
  "im": {},
  "aiCredits": {},
  "logging": {},
  "permissions": {}
}

Field	Purpose
iotPlatform	Selected IoT provider and each provider's connection parameters.
mqtt	MQTT broker, browser WebSocket URL, connection behavior, auth, TLS, and topic templates.
models	Primary agent model, vision model, and Jev decision model.
voice	Voice WebSocket service, voice region, provider, and ASR/TTS settings.
im	Feishu, DingTalk, Discord, Telegram, Slack, and related IM channels.
aiCredits	AI credit policy. Device balances and usage records use separate storage; see AI Credits for management.
logging	Log level, console output, file output, and rotation.
permissions	Tool editor, write_file, execute_command, and allowed command prefixes.

Webhook connections, workflows, scheduled tasks, and per-agent configuration use their own data stores. Edit an agent's recognition vocabulary and existing wait feedback from its card's More → Configuration overview; the configured response style is read-only there.

Example

This local example shows only common fields for devices managed directly by Device Agent. The actual file contains the full structure; other providers use their own model and topic contracts.

{
  "version": 1,
  "iotPlatform": {
    "providerId": "default",
    "config": {}
  },
  "mqtt": {
    "brokerUrl": "mqtt://broker.example.com:1883",
    "wsUrl": "wss://broker.example.com:8084/mqtt",
    "clientId": "device-agent-gateway",
    "protocolVersion": 5,
    "username": "device-agent",
    "password": "secret",
    "tls": {
      "enabled": false,
      "rejectUnauthorized": true,
      "caFile": "",
      "certFile": "",
      "keyFile": "",
      "keyPassphrase": "",
      "serverName": ""
    },
    "topics": {
      "deviceCommand": "device-agent/{productId}/device/{deviceId}/commands",
      "deviceResponse": "device-agent/{productId}/device/{deviceId}/responses",
      "telemetry": "v1/{productId}/{deviceId}/telemetry",
      "event": "v1/{productId}/{deviceId}/event"
    }
  },
  "models": {
    "agent": {
      "provider": "openai",
      "model": "gpt-5.5",
      "baseUrl": "",
      "apiKey": "sk-...",
      "codexAuthFile": "",
      "maxIterations": 40,
      "reasoningEnabled": false,
      "reasoningEffort": "medium"
    },
    "vision": {
      "enabled": true,
      "provider": "auto",
      "model": "",
      "apiKey": "",
      "timeoutMs": 60000
    }
  }
}

Editing the File Directly

Direct local file edits are useful for backup restore, bulk deployment, or environments without console access. When editing:

• Keep version: 1.
• Use valid JSON. Comments and trailing commas are not allowed.
• Keep {productId} and {deviceId} placeholders in MQTT topic templates.
• TLS certificate paths can be absolute or relative to the runtime home.
• Restart Device Agent after editing the file to apply changes.
• The file can contain model, MQTT, voice, or IM credentials. Protect backups as sensitive configuration and keep them out of source control.

If the file is invalid, Device Agent reports the configuration path during startup. To recover, back up the current file, remove config.json, and restart Device Agent to regenerate a default configuration.

Relationship with .env

In a local runtime, .env writes matching configuration fields at startup. If you edit config.json directly while the same variable still exists in .env, the .env value is written again on the next restart.

Values that are usually kept in .env are deployment differences, such as HTTP bind address, database, A2A identity, and secret injection. Values that are usually kept in config.json are daily MQTT, model, voice, IM, logging, and permission settings maintained from the console.

On the platform, non-secret variables seed the first shared configuration only; saved values take precedence afterward. Deployment credentials are read at every startup and kept out of regular shared configuration fields. Credentials obtained through ThingsNeural login are managed by its authorization flow. See Environment Variables.