Connection parameters

This page provides a complete reference for all connection parameters when connecting to CloudSignal.

Endpoints

CloudSignal exposes two encrypted endpoints.

Transport	URL
MQTT over TLS	`mqtts://mqtt.cloudsignal.app:8883`
MQTT over WSS	`wss://connect.cloudsignal.app:18885/`

Use the TLS endpoint for backend services and native MQTT clients. Use the WSS endpoint for browser clients and WebSocket transport.

Authentication

Required parameters

Parameter	Format	Example
Username	`{mqtt_username}@{organization_id}`	`agent-001@a1b2c3d4-e5f6-7890-abcd-ef1234567890`
Password	String	Your client password

Username format

The username consists of two parts separated by @:

{mqtt_username}@{organization_id}

Where:
  mqtt_username   = The name you assigned when creating the client
  organization_id = Your CloudSignal organization UUID

Find your organization ID in Settings → Organization in the dashboard.

TLS configuration

Certificate requirements

CloudSignal uses certificates signed by well-known Certificate Authorities. Most MQTT clients automatically trust these certificates.

You don't need to:

Download or install custom certificates.
Configure CA bundles manually.
Use self-signed certificates.

If your client requires explicit TLS configuration, the snippets below cover the common cases.

// Most clients - just enable TLS
const client = mqtt.connect('mqtts://mqtt.cloudsignal.app:8883', {
  username: 'user@org',
  password: 'pass',
});

// If you need explicit config
const client = mqtt.connect('mqtts://mqtt.cloudsignal.app:8883', {
  username: 'user@org',
  password: 'pass',
  rejectUnauthorized: true, // Verify server certificate (default)
});

import ssl

# Standard TLS (uses system CA certificates)
client.tls_set(cert_reqs=ssl.CERT_REQUIRED)
client.connect('mqtt.cloudsignal.app', 8883)

Client ID

The client ID identifies your connection. If not specified, the broker generates one.

Recommendations

Use case	Client ID strategy
Single agent or worker	Use a stable identifier: `worker-abc123`
User session	Include user ID: `user-12345-session`
Serverless	Random per invocation: `lambda-{uuid}`
Browser	Random or session-based

Example

const client = mqtt.connect('mqtts://mqtt.cloudsignal.app:8883', {
  clientId: 'agent-research-01',
  username: 'agent@org-id',
  password: 'password',
});

Client IDs must be unique per organization. Two clients with the same ID will cause disconnection loops.

Keep alive

Keep alive determines how often the client sends ping packets to maintain the connection.

Setting	Default	Recommended
Keep alive	60 seconds	30-120 seconds

const client = mqtt.connect('mqtts://mqtt.cloudsignal.app:8883', {
  keepalive: 60, // seconds
  // ... other options
});

Guidelines:

Mobile apps: higher values (120s) to save battery.
Critical agents: lower values (30s) for faster disconnect detection.
Web apps: default (60s) is usually fine.

Clean session

Clean session determines whether the broker stores session state.

Value	Behavior
`true`	Start fresh; no queued messages, no persistent subscriptions
`false`	Resume previous session; receive queued QoS 1 or QoS 2 messages

const client = mqtt.connect('mqtts://mqtt.cloudsignal.app:8883', {
  clean: true, // or false for persistent sessions
  clientId: 'my-client', // Required for persistent sessions
  // ... other options
});

Persistent sessions (clean: false) require a consistent clientId. Without it, the broker can't identify returning clients.

MQTT protocol version

CloudSignal supports both MQTT 3.1.1 and MQTT 5.0.

// MQTT 5.0 (recommended)
const client = mqtt.connect('mqtts://mqtt.cloudsignal.app:8883', {
  protocolVersion: 5,
  // ... other options
});

// MQTT 3.1.1 (default in most libraries)
const client = mqtt.connect('mqtts://mqtt.cloudsignal.app:8883', {
  protocolVersion: 4, // MQTT 3.1.1
  // ... other options
});

MQTT 5.0 features

Feature	What it adds
Reason codes	Detailed error information
User properties	Custom key-value metadata
Topic aliases	Reduced bandwidth for repeated topics
Message expiry	Automatic message cleanup
Shared subscriptions	Load balancing across clients

Reconnection

Configure automatic reconnection for connection drops:

const client = mqtt.connect('mqtts://mqtt.cloudsignal.app:8883', {
  reconnectPeriod: 1000, // Try every one second
  connectTimeout: 30 * 1000, // 30 second timeout
  // ... other options
});

Best practices:

Use exponential backoff in custom reconnect logic.
Re-subscribe after reconnection if using clean: true.
Implement max retry limits for serverless functions.

Complete example

const mqtt = require('mqtt');

const client = mqtt.connect('mqtts://mqtt.cloudsignal.app:8883', {
  // Authentication
  username: 'agent-001@a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  password: process.env.MQTT_PASSWORD,

  // Client identification
  clientId: `agent-001-${Date.now()}`,

  // Protocol
  protocolVersion: 5,

  // Connection behavior
  clean: true,
  keepalive: 60,
  connectTimeout: 30000,

  // Reconnection
  reconnectPeriod: 1000,

  // TLS (automatic for mqtts://)
  rejectUnauthorized: true,
});

client.on('connect', () => {
  console.log('Connected to CloudSignal');
});

client.on('error', (err) => {
  console.error('Connection error:', err);
});

client.on('close', () => {
  console.log('Connection closed');
});

Next steps

Troubleshooting - Diagnose common connection problems
JavaScript SDK - Higher-level browser and Node.js client

On this page