Environment Variables

Device Agent reads process environment variables and then tries to load .env at startup for deployment, secrets, and environment-specific values. Supported fields are written into .device_agent/config.json; startup-only values such as HTTP binding, database, A2A identity, and extra IM channels are not.

In development, .env is usually in the repository root. The installed binary reads .env from the install directory. On macOS/Linux, the default path is ${XDG_DATA_HOME:-$HOME/.local/share}/device-agent/current/.env. To affect only one startup, pass the variables directly before device-agent.

ENV_FILE="${XDG_DATA_HOME:-$HOME/.local/share}/device-agent/current/.env"
touch "$ENV_FILE"

MQTT

Variable	Notes
MQTT_BROKER_URL	MQTT broker URL used by the gateway and device-side clients, such as mqtt://localhost:1883.
VITE_MQTT_WS_URL	MQTT broker WebSocket URL used by the browser, such as ws://localhost:8083/mqtt.
MQTT_CLIENT_ID	Client ID used by the gateway MQTT connection.
MQTT_PROTOCOL_VERSION	MQTT protocol version. Supports 4 and 5.
MQTT_KEEPALIVE_SECONDS / MQTT_KEEP_ALIVE_SECONDS	Keep Alive interval.
MQTT_CONNECT_TIMEOUT_MS	Connection timeout.
MQTT_AUTO_RECONNECT	Whether to reconnect automatically.
MQTT_RECONNECT_PERIOD_MS	Reconnect interval.
MQTT_CLEAN_START	Whether to use Clean Start.
MQTT_SESSION_EXPIRY_INTERVAL_SECONDS	MQTT 5 session expiry interval.
MQTT_USERNAME / MQTT_PASSWORD	Common MQTT credentials for gateway and device-side clients.
VITE_MQTT_USERNAME / VITE_MQTT_PASSWORD	Browser-side MQTT credentials. Use only when the browser must connect directly to the broker.

TLS variables:

Variable	Notes
MQTT_TLS_ENABLED	Enable MQTT TLS.
MQTT_TLS_INSECURE	Set to true to disable server certificate verification.
MQTT_TLS_REJECT_UNAUTHORIZED	Whether to verify the server certificate.
MQTT_TLS_CA_FILE	CA certificate path.
MQTT_TLS_CERT_FILE	Client certificate path.
MQTT_TLS_KEY_FILE	Client private key path.
MQTT_TLS_KEY_PASSPHRASE	Client private key passphrase.
MQTT_TLS_SERVER_NAME	TLS Server Name.

Topic template variables:

MQTT_TOPIC_PRODUCT_IN=device-agent/{productId}/in
MQTT_TOPIC_PRODUCT_OUT=device-agent/{productId}/out
MQTT_TOPIC_DEVICE_IN=device-agent/{productId}/device/{deviceId}/in
MQTT_TOPIC_DEVICE_OUT=device-agent/{productId}/device/{deviceId}/out
MQTT_TOPIC_DEVICE_COMMAND=device-agent/{productId}/device/{deviceId}/commands
MQTT_TOPIC_DEVICE_RESPONSE=device-agent/{productId}/device/{deviceId}/responses
MQTT_TOPIC_TELEMETRY=v1/{productId}/{deviceId}/telemetry
MQTT_TOPIC_EVENT=v1/{productId}/{deviceId}/event
MQTT_TOPIC_NTP_REQUEST=device-agent/{productId}/device/{deviceId}/ntp/request
MQTT_TOPIC_NTP_RESPONSE=device-agent/{productId}/device/{deviceId}/ntp/response

Topic templates must keep the {productId} and {deviceId} placeholders. See MQTT Access for topics and payloads.

Models and Vision

Variable	Notes
LLM_PROVIDER	Primary agent model provider.
LLM_MODEL	Primary agent model name.
LLM_BASE_URL	Custom model service URL, commonly used for OpenAI-compatible endpoints or local model services.
LLM_API_KEY	Generic model API key.
OPENAI_API_KEY / ANTHROPIC_API_KEY / KIMI_API_KEY / QWEN_API_KEY	Provider-specific API keys.
OPENAI_CODEX_AUTH_FILE	Codex auth file path for the openai-codex provider.
OPENAI_CODEX_ACCESS_TOKEN	Access token for the openai-codex provider.
AGENT_MAX_ITERATIONS	Maximum iterations for one agent task.
VISION_ENABLED	Whether vision is enabled.
VISION_PROVIDER	Vision provider. Supports auto and dashscope.
VISION_MODEL	Vision model name.
VISION_API_KEY	Vision model API key.
VISION_TIMEOUT_MS	Vision analysis timeout.

With VISION_PROVIDER=auto, Device Agent tries to reuse the primary agent model when it supports image input. To use a separate vision model, set VISION_PROVIDER=dashscope, VISION_MODEL, and VISION_API_KEY.

HTTP, Frontend, and Data Storage

Variable	Notes
AGENT_GATEWAY_HTTP_HOST	Console and HTTP API bind address. Defaults to 127.0.0.1. Use 0.0.0.0 for server IP or LAN access.
AGENT_GATEWAY_HTTP_PORT	Console and HTTP API port. Defaults to 3000.
AGENT_GATEWAY_HTTP_TLS_ENABLED	Whether to serve the console and HTTP API over direct HTTPS. If omitted, providing both certificate and key files enables TLS.
AGENT_GATEWAY_HTTP_TLS_CERT_FILE / AGENT_GATEWAY_HTTP_TLS_KEY_FILE	TLS certificate and private key paths for direct HTTPS. Relative paths are resolved from the workspace root.
AGENT_GATEWAY_HTTP_TLS_PASSPHRASE	TLS private key passphrase for direct HTTPS.
VITE_API_BASE_URL	Frontend API base URL. Usually not needed when same-origin proxying is used.
VITE_DEVICE_AGENT_PENDING_TIMEOUT_MS	Timeout for console Device Agent creation or pending responses.
DATABASE_DRIVER	Data storage driver. The default uses local storage; set postgres to use PostgreSQL.
DATABASE_URL	PostgreSQL connection URL. Required only when DATABASE_DRIVER=postgres.
WEBHOOK_CREDENTIAL_MASTER_KEY	Required 32-byte Base64 key for PostgreSQL deployments. Use the same value on every Gateway.

Frontend variables are read by the frontend dev server or build process. Restart the frontend service or rebuild after changing them.

Enable Direct HTTPS

Set a certificate and matching private key, then restart Device Agent:

AGENT_GATEWAY_HTTP_HOST=0.0.0.0
AGENT_GATEWAY_HTTP_PORT=3000
AGENT_GATEWAY_HTTP_TLS_ENABLED=true
AGENT_GATEWAY_HTTP_TLS_CERT_FILE=/etc/device-agent/fullchain.pem
AGENT_GATEWAY_HTTP_TLS_KEY_FILE=/etc/device-agent/privkey.pem

The console and HTTP API then use https://<host>:3000. Certificate and key must be configured together. Relative paths are resolved from the workspace or installation root. Providing both files also enables HTTPS when AGENT_GATEWAY_HTTP_TLS_ENABLED is omitted; setting it to false keeps HTTP enabled instead. HTTPS encrypts traffic but does not add user authentication, so restrict access to a trusted network or an authenticated gateway.

See Installation for browser and certificate verification steps.

Configure the Webhook Key

For PostgreSQL, generate WEBHOOK_CREDENTIAL_MASTER_KEY once with openssl rand -base64 32, use the same value on every Gateway, and keep a secure backup. Do not rotate it casually.

SQLite deployments do not require this variable. See Webhook for connection setup.

Voice

Variable	Notes
VOICE_ENABLED	Whether the voice channel is enabled.
VOICE_HOST	Voice service bind address. Defaults to 127.0.0.1; use 0.0.0.0 for LAN or server access.
VOICE_PORT	Voice service bind port. Defaults to 3001.
VITE_ASR_SAMPLE_RATE	ASR sample rate used by browser audio capture.
VOICE_REGION	Voice region. Supports cn, us, eu, and global.
VOICE_TLS_ENABLED	Whether voice service TLS is enabled.
VOICE_TLS_CERT_FILE / VOICE_TLS_KEY_FILE	Voice service TLS certificate and private key paths.
VOICE_TLS_PASSPHRASE	Voice service TLS private key passphrase.

Speech provider variables:

Provider	Variables
Volcengine	VOLCENGINE_SPEECH_APP_ID, VOLCENGINE_SPEECH_ACCESS_KEY, VOLCENGINE_ASR_RESOURCE_ID, VOLCENGINE_ASR_LANGUAGE, VOLCENGINE_TTS_RESOURCE_ID, VOLCENGINE_TTS_VOICE, VOLCENGINE_TTS_VOICES, VOLCENGINE_TTS_EXPLICIT_LANGUAGE, VOLCENGINE_TTS_SAMPLE_RATE
Alibaba Cloud DashScope	ALIYUN_DASHSCOPE_API_KEY, ALIYUN_ASR_MODEL, ALIYUN_ASR_LANGUAGE, ALIYUN_TTS_MODEL, ALIYUN_TTS_VOICE, ALIYUN_TTS_VOICES, ALIYUN_TTS_SAMPLE_RATE
AWS	AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, AWS_TRANSCRIBE_LANGUAGE_CODE, AWS_POLLY_VOICE, AWS_POLLY_SAMPLE_RATE
ElevenLabs	ELEVENLABS_API_KEY, ELEVENLABS_API_ENDPOINT, ELEVENLABS_ASR_MODEL_ID, ELEVENLABS_ASR_LANGUAGE, ELEVENLABS_TTS_MODEL_ID, ELEVENLABS_TTS_VOICE, ELEVENLABS_TTS_VOICES, ELEVENLABS_TTS_SAMPLE_RATE

For voice configuration details, see Voice Configuration. For usage flow, see Voice Interaction.

IM

These channels can also be configured from the console settings page:

Channel	Variables
Feishu	FEISHU_ENABLED, FEISHU_APP_ID, FEISHU_APP_SECRET, FEISHU_ENCRYPT_KEY, FEISHU_VERIFICATION_TOKEN, FEISHU_ALLOW_FROM
DingTalk	DINGTALK_ENABLED, DINGTALK_CLIENT_ID, DINGTALK_CLIENT_SECRET, DINGTALK_ALLOW_FROM
Discord	DISCORD_ENABLED, DISCORD_BOT_TOKEN, DISCORD_ALLOW_FROM
Telegram	TELEGRAM_ENABLED, TELEGRAM_BOT_TOKEN, TELEGRAM_ALLOW_FROM
Slack	SLACK_ENABLED, SLACK_BOT_TOKEN, SLACK_APP_TOKEN, SLACK_SIGNING_SECRET, SLACK_ALLOW_FROM, SLACK_CHANNEL_DIRECT_ENABLED

Additional IM channels are env-only and do not appear in the console settings page:

Channel	Variables
WhatsApp	WHATSAPP_ENABLED, WHATSAPP_BRIDGE_URL, WHATSAPP_BRIDGE_TOKEN, WHATSAPP_ALLOW_FROM
QQ	QQ_ENABLED, QQ_APP_ID, QQ_APP_SECRET, QQ_TOKEN, QQ_SANDBOX, QQ_ALLOW_FROM
Matrix	MATRIX_ENABLED, MATRIX_HOMESERVER_URL, MATRIX_ACCESS_TOKEN, MATRIX_AUTOJOIN, MATRIX_ALLOW_FROM
MoChat	MOCHAT_ENABLED, MOCHAT_SERVER_URL, MOCHAT_TOKEN, MOCHAT_BOT_NAME, MOCHAT_ALLOW_FROM
Email	EMAIL_ENABLED, EMAIL_IMAP_HOST, EMAIL_IMAP_PORT, EMAIL_IMAP_USER, EMAIL_IMAP_PASSWORD, EMAIL_IMAP_TLS, EMAIL_SMTP_HOST, EMAIL_SMTP_PORT, EMAIL_SMTP_USER, EMAIL_SMTP_PASSWORD, EMAIL_SMTP_TLS, EMAIL_FROM_ADDRESS, EMAIL_POLL_INTERVAL_MS, EMAIL_ALLOW_FROM

See IM Access for platform-specific setup.

Logging

Variable	Notes
LOG_LEVEL	Log level. Supports debug, info, warn, and error.
LOG_CONSOLE_ENABLED	Whether to write logs to the console.
LOG_FILE_ENABLED	Whether to write logs to files.
LOG_DIR	Log directory. Relative paths resolve under the runtime home.
LOG_MAX_SIZE_MB	Maximum size of one log file.
LOG_RETENTION_DAYS	Log retention days.
LOG_MAX_TOTAL_SIZE_MB	Maximum total log file size.
LOG_TIMEZONE	File log timestamp timezone: system or utc.

See Logs for logging usage.

Tool Permissions

Variable	Notes
ENABLE_TOOL_EDITOR_MUTATIONS	Reapplies and persists the tool editor save/delete permission on every startup.
ENABLE_FILE_WRITE_TOOL	Reapplies and persists the write_file tool permission on every startup.
ENABLE_EXECUTE_COMMAND_TOOL	Reapplies and persists the execute_command tool permission on every startup.
ALLOWED_EXEC_COMMAND_PREFIXES	Reapplies and persists the allowed command prefixes on every startup. An empty value clears the allowlist.
DANGEROUSLY_BYPASS_TOOL_PERMISSIONS	Server-only startup flag. It is not written to config.json or exposed in the console. Set to true to bypass file-write approvals, command approvals and allowlists, shell safety checks, and tool editor mutation gates. This is not a sandbox: bypassed writes can modify executable code or tool extensions, and commands run with the Gateway process's host permissions. Use it only when the Agent, workspace, and all Gateway secrets are trusted.

A2A

Variable	Notes
A2A_ORG_ID / A2A_UNIT_ID	Organization and unit identity used for A2A registration and discovery. Both default to default.

See A2A for A2A usage.