MQTT Mock Server

Mock Alpha includes an embedded MQTT broker (powered by aedes). It starts automatically with the dashboard and lets you push mock events to your app — either manually from the dashboard or automatically when an HTTP endpoint is hit.

Any MQTT 3.1.1 client works — Paho (Android/Java), CocoaMQTT (iOS), mqtt_client (Flutter), MQTT.js (web/Node), mosquitto CLI.

Connection details

The connection details are shown on the MQTT page of each project. Browsers can only use the WebSocket port; native clients can use either.

Authentication

Each project has its own MQTT namespace. Clients authenticate using the project credentials.

Kotlin (Paho):

val options = MqttConnectOptions().apply {
    userName = "<project-id>"
    password = "<api-key>".toCharArray()
    isCleanSession = true
}

val client = MqttClient("tcp://mock-alpha.your-domain.com:1883", MqttClient.generateClientId())
client.connect(options)

JavaScript (MQTT.js, browser or Node):

import mqtt from 'mqtt'

const client = mqtt.connect('ws://mock-alpha.your-domain.com:1884', {
  username: '<project-id>',
  password: '<api-key>',
})

Topic isolation

Topics are isolated per project. When you configure a topic as devices/status, Mock Alpha internally prefixes it with {projectId}/devices/status. Your app subscribes and receives messages on devices/status — the prefix is transparent.

// Subscribe to the raw topic — no project prefix needed
client.subscribe("devices/status") { topic, message ->
    val payload = String(message.payload)
    // handle event
}

client.subscribe('devices/status')
client.on('message', (topic, payload) => {
  // handle event
})

Configuring topics

On the MQTT page of your project:

1. Click + Add Topic
2. Enter the topic path (e.g., devices/status)
3. Enter the JSON payload — you can use response templates
4. Optionally link it to an HTTP endpoint for auto-publish
5. Set an optional delay in milliseconds before publishing

Manual publish

Click Publish Now on any topic row to immediately push the payload to all connected clients subscribed to that topic.

Auto-publish on HTTP hit

Link a topic to an HTTP endpoint. Whenever Mock Alpha serves a mock response for that endpoint, it automatically publishes the MQTT topic payload — after the HTTP response is returned (fire-and-forget, no latency impact).

Example flow:

App → GET /api/mock/devices/123
    │
    ├── HTTP response returned immediately (from scenario)
    │
    └── [async] MQTT publish: topic=devices/status
                              payload={"deviceId":"123","event":"polled"}

This lets you simulate workflows where an HTTP action triggers a real-time event.

Template placeholders in MQTT payloads

Use {{request.X}} placeholders in the payload JSON:

{
  "deviceId": "{{request.path.id}}",
  "requestedBy": "{{request.header.x-user-id}}",
  "event": "status-requested"
}

The same request context that resolved the HTTP response is used to resolve the MQTT payload.

Publish log

The Publish Log tab shows a history of all MQTT publishes with:

• Timestamp
• Topic
• Payload (expandable)
• Triggered by (Manual / endpoint name)

The log auto-refreshes every 5 seconds.

Ports in use

If ports 1883 or 1884 are already in use on the host machine, the broker will fail to start and log a clear error. You can override the ports via environment variables:

MQTT_TCP_PORT=1883
MQTT_WS_PORT=1884

The dashboard will still function even if the MQTT broker fails to start. On a deployed instance, make sure both ports are reachable from your clients — see Self-Hosting.

QoS and limitations

The current release uses QoS 0 (fire-and-forget) for all publishes. The following are not yet supported:

• Retained messages
• QoS 1 or QoS 2
• Persistent sessions
• Wildcard subscriptions from the dashboard
• Scheduled / recurring auto-publish
• Incoming MQTT → HTTP trigger (reverse direction)