Environment Variables

Environment variables configure service addresses, model credentials, and other deployment options.

Set Environment Variables

Configuration scope	Apply behavior
Local console settings	Process variables and .env override matching saved console values at every startup.
Platform console settings	Environment variables initialize settings once; later changes use saved console values. Credentials come from the deployment environment.
Startup settings and deployment credentials	HTTP binding, database, service identity, A2A identity, and additional IM channels always use the deployment environment. Restart affected services after changes.

Local development uses .env in the repository root; installed binaries use .env in the installation directory. The default macOS/Linux path is shown below. For a single startup, set variables before the startup command.

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

Deployment administrators maintain platform variables; see Platform Deployment and Platform Operations. For daily settings, see Console Settings; for individual prompts, vocabulary, and responses, see Device Agent Configuration.

IoT Provider

Variable	Notes
IOT_PLATFORM_PROVIDER_ID	Initial IoT provider: default, fleets, or thingsneural.
FLEETS_API_URL	Fleets management API URL.
FLEETS_API_KEY / FLEETS_API_SECRET / FLEETS_BEARER_TOKEN	Fleets credentials injected through the deployment environment.
FLEETS_MQTT_BROKER_URL / FLEETS_MQTT_WEBSOCKET_URL	Fleets MQTT and browser WebSocket URLs.
THINGSNEURAL_URL / THINGSNEURAL_API_URL	ThingsNeural service URL; the latter is a compatibility alias.
THINGSNEURAL_ACCESS_KEY / THINGSNEURAL_SECRET_KEY	ThingsNeural connection credentials.
THINGSNEURAL_PROJECT_ID / THINGSNEURAL_CATEGORY_ID	ThingsNeural project and category identifiers.
THINGSNEURAL_MQTT_URL / THINGSNEURAL_CLIENT_API_URL / THINGSNEURAL_LOGIN_URL	MQTT, client API, and login URLs.

Configure the selected provider's parameters; see IoT Platform Integration.

MQTT

Variable	Notes
MQTT_BROKER_URL	Broker URL for the gateway and devices, such as mqtt://localhost:1883.
VITE_MQTT_WS_URL	Browser MQTT WebSocket URL, such as ws://localhost:8083/mqtt.
MQTT_CLIENT_ID	Gateway MQTT client ID.
MQTT_PROTOCOL_VERSION	MQTT protocol version. Supports 4 and 5.
MQTT_KEEPALIVE_SECONDS / MQTT_KEEP_ALIVE_SECONDS	Keep Alive interval, in seconds.
MQTT_CONNECT_TIMEOUT_MS	Connection timeout, in milliseconds.
MQTT_AUTO_RECONNECT	Whether to reconnect automatically.
MQTT_RECONNECT_PERIOD_MS	Reconnect interval, in milliseconds.
MQTT_CLEAN_START	Whether to use Clean Start.
MQTT_SESSION_EXPIRY_INTERVAL_SECONDS	MQTT 5 session expiry interval, in seconds.
MQTT_USERNAME / MQTT_PASSWORD	MQTT credentials for the gateway and devices.
VITE_MQTT_USERNAME / VITE_MQTT_PASSWORD	MQTT credentials for direct browser connections 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 templates apply only to the default provider; Fleets and ThingsNeural use their native topic contracts:

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 URL 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.
DOUBAO_API_KEY / ARK_API_KEY	Volcengine Ark credentials for doubao, checked in order: DOUBAO_API_KEY, ARK_API_KEY, LLM_API_KEY. Not interchangeable with VOLCENGINE_SPEECH_*.
CLOUDFLARE_API_KEY	API key for Cloudflare Workers AI or AI Gateway.
CLOUDFLARE_ACCOUNT_ID	Cloudflare Account ID, used when the corresponding console field is empty.
CLOUDFLARE_GATEWAY_ID	AI Gateway ID for cloudflare-ai-gateway, used when the corresponding console field is empty.
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.
LLM_REASONING_ENABLED	Whether model reasoning (thinking) is enabled. Defaults to false.
LLM_REASONING_EFFORT	Reasoning effort: minimal, low, medium (default), high, xhigh, or max. Requires reasoning to be enabled and model support; the console shows the supported range.
VISION_ENABLED	Whether vision is enabled.
VISION_PROVIDER	auto reuses an agent model that supports images; dashscope uses a separate vision model.
VISION_MODEL	DashScope vision model name.
VISION_API_KEY	DashScope vision model API key.
VISION_TIMEOUT_MS	Vision analysis timeout, in milliseconds.
TYPESAFE_API_KEY	API key for the Jev decision model. Initializes the local value; injected only into the platform Worker.

See LLM Configuration for model and reasoning options, and Vision Configuration for vision options. Change legacy LLM_PROVIDER=kimi to moonshotai-cn; keep the model ID and API key unchanged.

auto reuses the agent model's API configuration; dashscope requires separate VISION_MODEL and VISION_API_KEY values.

HTTP, Frontend, and Data Storage

HTTP and Frontend

Variable	Notes
AGENT_GATEWAY_HTTP_HOST	Console and API bind address: 127.0.0.1 locally, 0.0.0.0 for server or LAN access. Platform values follow deployment configuration.
AGENT_GATEWAY_HTTP_PORT	Console and HTTP API port. Defaults to 3000.
AGENT_GATEWAY_HTTP_TLS_ENABLED	true enables direct HTTPS; false uses HTTP. If omitted, providing both certificate and key enables HTTPS.
AGENT_GATEWAY_HTTP_TLS_CERT_FILE / AGENT_GATEWAY_HTTP_TLS_KEY_FILE	HTTPS certificate and private key paths; configure both. Relative paths use the workspace or installation root.
AGENT_GATEWAY_HTTP_TLS_PASSPHRASE	HTTPS private key passphrase.
VITE_API_BASE_URL	Frontend API base URL; usually unnecessary with a same-origin proxy.
VITE_DEVICE_AGENT_PENDING_TIMEOUT_MS	Timeout for console Device Agent creation or responses, in milliseconds.

VITE_ variables are read by the frontend dev server or build. Restart the frontend or rebuild after changes.

Data Storage and Service Roles

Variable	Notes
DATABASE_DRIVER	Local runtimes use sqlite (default); platform deployments use postgres.
DATABASE_URL	Platform PostgreSQL connection string. Verify certificates in production; use sslmode=disable only for local development.
DEVICE_AGENT_ROLE	Platform role: cloud-api, cloud-worker, or cloud-ingress. cloud-all runs all roles in one process for development only.

Authentication and Licensing

Variable	Notes
AGENT_GATEWAY_API_TOKEN	Optional Bearer token for service calls, at least 32 characters.
AGENT_GATEWAY_CONSOLE_AUTH_ENABLED	Set to true locally to enable provider SSO; requires provider console-login support. The platform enables SSO checks automatically for these providers.
AGENT_GATEWAY_CONSOLE_SESSION_SECRET	Provider console-session signing secret: at least 32 random characters, identical across API replicas.
WEBHOOK_CREDENTIAL_MASTER_KEY	Required Webhook credential encryption key for PostgreSQL: a Base64-encoded 32-byte key.
DEVICE_AGENT_LICENSE_ADMIN_TOKEN	Separate credential for signed License imports: at least 32 characters, distinct from the service token and session secret. Imports are unavailable without it.
DEVICE_AGENT_PUBLIC_BASE_URL	Public console URL. Set when a reverse proxy terminates HTTPS, to validate browser License import origins.
DEVICE_AGENT_LICENSE_FILE	Optional signed license file for first activation; renew later from License settings.

Service tokens authenticate service calls; they do not provide end-user identity or role permissions. HTTPS encrypts transport. Shared access requires a trusted network or authenticated entry point.

See Platform Deployment for service configuration and License for request licensing. AI Credits manages device consumption policies separately.

Enable Direct HTTPS

Example for a local service; restart Device Agent after configuration:

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

After restarting, access the console and HTTP API at https://<host>:3000. See Installation for browser and certificate verification.

Platform Monitoring

The deployment administrator enables metric collection using the delivered runbook and configures Prometheus on the platform API service:

Variable	Notes
DEVICE_AGENT_PROMETHEUS_URL	Prometheus HTTP/HTTPS base URL, without credentials, query, or fragment. Monitoring is unavailable if unset.
DEVICE_AGENT_PROMETHEUS_NAMESPACE	Optional namespace filter: a lowercase DNS label matching the metrics' device_agent_namespace label.

Voice

Variable	Notes
VOICE_ENABLED	Whether the voice channel is enabled.
VOICE_HOST	Voice bind address: 127.0.0.1 locally, 0.0.0.0 for LAN or server access. The platform publishes a public URL through its deployment entry point.
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
Aliyun DashScope	ALIYUN_DASHSCOPE_API_KEY, ALIYUN_ASR_MODEL, ALIYUN_ASR_LANGUAGE, ALIYUN_ASR_VOCABULARY_ENABLED, 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

See Voice Configuration for settings and Voice Interaction for usage.

IM

Settings → Channels supports these channels. Local installations allow credential edits; the platform allows non-secret edits and receives credentials from the deployment environment.

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

These channels are configured only through environment variables:

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

File output and rotation apply to local installations. See Logs and Platform Operations for platform logs and retention.

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.

Tool Permissions

Variable	Notes
ENABLE_TOOL_EDITOR_MUTATIONS	Tool editor save and delete permission.
ENABLE_FILE_WRITE_TOOL	write_file tool permission.
ENABLE_EXECUTE_COMMAND_TOOL	execute_command tool permission.
ALLOWED_EXEC_COMMAND_PREFIXES	Allowed command prefixes. An empty value clears the allowlist.
DANGEROUSLY_BYPASS_TOOL_PERMISSIONS	Server-only startup flag, excluded from config.json and the console. Set to true to bypass tool permission checks.

Bypass mode skips file-write approvals, command approvals and allowlists, shell safety checks, and tool editor mutation gates. Writes can modify executable code or tool extensions, and commands run with the Gateway's host permissions. Enable only when the Agent, workspace, and all Gateway credentials are trusted.

Tool permissions follow the apply rules above; they do not provide console user or role management.

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.