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://connect.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.

import CloudSignal from '@cloudsignal/mqtt-client';

// The SDK enables TLS automatically for mqtts:// and wss:// hosts
const client = new CloudSignal();

await client.connect({
  host: 'mqtts://connect.cloudsignal.app:8883',
  username: 'user@org',
  password: 'pass',
});

import ssl

# Standard TLS (uses system CA certificates)
client.tls_set(cert_reqs=ssl.CERT_REQUIRED)
client.connect('connect.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 = new CloudSignal();

await client.connect({
  host: 'mqtts://connect.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 = new CloudSignal({
  keepalive: 60, // seconds
  // ... other options
});

await client.connect({
  host: 'mqtts://connect.cloudsignal.app:8883',
  // ... credentials
});

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 = new CloudSignal({
  cleanSession: true, // or false for persistent sessions
  // ... other options
});

await client.connect({
  host: 'mqtts://connect.cloudsignal.app:8883',
  clientId: 'my-client', // Required for persistent sessions
  // ... credentials
});

Persistent sessions (cleanSession: 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 = new CloudSignal({
  protocolVersion: 5,
  // ... other options
});

// MQTT 3.1.1
const client = new CloudSignal({
  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 = new CloudSignal({
  reconnectPeriod: 1000, // Try every one second
  connectTimeout: 30 * 1000, // 30 second timeout
  // ... other options
});

// React to reconnection events with setter callbacks
client.setReconnectingCallback((attempt) => {
  console.log(`Reconnecting (attempt ${attempt})`);
});

client.setOnlineCallback(() => {
  console.log('Reconnected');
  // Re-subscribe idempotently here
});

Best practices:

Re-subscribe after reconnection if using cleanSession: true.
Re-subscribe idempotently inside setOnlineCallback so a returning session restores its subscriptions.
Implement max retry limits for serverless functions.

Complete example

import CloudSignal from '@cloudsignal/mqtt-client';

const client = new CloudSignal({
  // Protocol
  protocolVersion: 5,

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

  // Reconnection
  reconnectPeriod: 1000,
});

// Register status callbacks before connecting
client.setOnlineCallback(() => {
  console.log('Connected to CloudSignal');
});

client.setOfflineCallback(() => {
  console.log('Connection closed');
});

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

await client.connect({
  host: 'mqtts://connect.cloudsignal.app:8883',

  // Authentication
  username: 'agent-001@a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  password: process.env.MQTT_PASSWORD,

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

Next steps

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

On this page