dsh-mqtt

Configuration reference

Option	Default	Description
url	mqtt://127.0.0.1:1883	mqtt, mqtts, ws, or wss broker URL.
namespace	local	Topic namespace; 1–64 topic-safe characters.
nodeId	dsh-node	Node topic segment; 1–64 topic-safe characters.
clientId	dsh-mqtt-{namespace}-{nodeId}	Stable MQTT client ID.
protocolVersion	5	5 for MQTT 5, 4 for MQTT 3.1.1.
clean	false	MQTT clean-session/start flag. Keep false for offline command delivery.
keepaliveSeconds	30	MQTT keepalive.
connectTimeoutMs	10000	Initial connection timeout.
reconnectPeriodMs	1000	Reconnect delay; 0 disables reconnect.
sessionExpirySeconds	86400	MQTT 5 Session expiry; ignored for MQTT 3.1.1.
username, password	unset	Direct broker credentials. Avoid storing password in a profile.
usernameEnv, passwordEnv	unset	Environment variable names containing broker credentials. Mutually exclusive with direct values.
caFile	unset	Absolute CA bundle path for TLS.
certFile, keyFile	unset	Client certificate and private key paths for mutual TLS.
rejectUnauthorized	true	Verify broker TLS certificates. Do not disable in production.
stateFile	.dsh-mqtt/state.json	Durable deduplication/result/Session-ownership JSON file.
workspaces	{}	Alias-to-directory allowlist for new Sessions.
defaultWorkspace	unset	Alias used when a new request omits workspace.
allowExternalSessions	false	Permit continuation of Sessions not recorded by this gateway. See the security warning above.
provider, model, maxTokens	current DSH profile selection	Optional Agent creation overrides. provider and model must be set together; otherwise the gateway reads ctx.agentDefaultModel.
capabilities	[]	Informational values published in online presence.
eventExposure	safe	safe normalized events or full raw event data.
maxMessageBytes	65536	Maximum inbound MQTT payload size.
maxMetadataBytes	8192	Maximum serialized metadata size; cannot exceed maxMessageBytes.
maxInputChars	32768	Maximum input length in JavaScript characters.
maxActiveRequests	16	Maximum accepted/active requests.
dedupTtlSeconds	604800	Terminal request/control retention.

Credentials and TLS

The gateway supports direct MQTT username/password values or environment-backed credentials. Prefer environment variables for unattended deployments so the password is not stored in the DSH profile.

Username/password without TLS

This is suitable only for a loopback interface, VPN, or otherwise trusted private network. MQTT username/password authentication does not encrypt the credentials or payload.

- id: mqtt-gateway
  config:
    url: mqtt://broker.internal.example:1883
    namespace: ullrai
    nodeId: mac-mini
    username: dsh-mac-mini
    password: replace-with-broker-password

The direct password form is shown for completeness. Do not commit a real password to the profile. Use mqtts:// or wss:// whenever traffic crosses an untrusted network.

Username/password over TLS

This is the recommended configuration for a cloud broker:

- id: mqtt-gateway
  config:
    url: mqtts://broker.example.com:8883
    namespace: ullrai
    nodeId: mac-mini
    usernameEnv: DSH_MQTT_USERNAME
    passwordEnv: DSH_MQTT_PASSWORD
    rejectUnauthorized: true
    stateFile: /var/lib/dsh-mqtt/state.json
    workspaces:
      repo-foo: /srv/repos/repo-foo

export DSH_MQTT_USERNAME='dsh-mac-mini'
export DSH_MQTT_PASSWORD='...'
npx @deepseek-ai/dsh --profile web

Use the exact hostname and port supplied by the broker. A public-CA certificate normally needs no caFile; hostname and certificate verification remain enabled by default. Secure WebSocket endpoints use wss:// with the provider's path and the same credential fields.

Custom CA and mutual TLS

For a private CA or a broker that requires a client certificate, add the relevant files to the TLS configuration:

- id: mqtt-gateway
  config:
    url: mqtts://broker.internal.example:8883
    namespace: ullrai
    nodeId: mac-mini
    usernameEnv: DSH_MQTT_USERNAME
    passwordEnv: DSH_MQTT_PASSWORD
    caFile: /etc/dsh-mqtt/ca.pem
    certFile: /etc/dsh-mqtt/client.pem
    keyFile: /etc/dsh-mqtt/client-key.pem
    rejectUnauthorized: true

caFile supplies the trusted CA bundle. certFile and keyFile enable mutual TLS and must be configured together when the broker requires them. A broker can require mTLS in addition to, or instead of, username/password authentication. Do not set rejectUnauthorized: false in production.