Quick start
Connect to CloudSignal and send your first message using @cloudsignal/mqtt-client.
This guide gets you sending and receiving MQTT messages in under five minutes using @cloudsignal/mqtt-client. You'll connect with a token, subscribe to a topic, and publish a message.
Install
npm install @cloudsignal/mqtt-clientConnect
The SDK supports two authentication paths. Pick the one that matches where your code runs.
import CloudSignal from '@cloudsignal/mqtt-client';
// In the browser, exchange an auth provider token (Supabase, Firebase, Auth0, Clerk)
const client = new CloudSignal({ preset: 'desktop' });
await client.connectWithToken({
organizationId: process.env.NEXT_PUBLIC_CLOUDSIGNAL_ORG_ID,
externalToken: session.access_token,
});
// → connection establishedServer-side, authenticate with your CloudSignal secret key instead:
const client = new CloudSignal({ preset: 'server' });
await client.connectWithToken({
organizationId: process.env.CLOUDSIGNAL_ORG_ID,
secretKey: process.env.CLOUDSIGNAL_SECRET_KEY,
userEmail: 'service@example.com',
});Never embed a secret key in browser code. See Key types for the split between publishable and secret keys.
Subscribe to a topic
Register a message handler before subscribing so you don't miss the first delivery.
client.onMessage((topic, message) => {
console.log(`received on ${topic}:`, message);
});
await client.subscribe('agents/agent-01/state');Publish a message
transmit serializes objects to JSON automatically.
client.transmit('agents/agent-01/state', {
status: 'idle',
load: 0.12,
});Complete example
A minimal end-to-end script that connects, subscribes, publishes, and tears down cleanly.
import CloudSignal from '@cloudsignal/mqtt-client';
async function main() {
const client = new CloudSignal({ preset: 'server' });
client.onMessage((topic, message) => {
console.log('new message:', topic, message);
});
await client.connectWithToken({
organizationId: process.env.CLOUDSIGNAL_ORG_ID,
secretKey: process.env.CLOUDSIGNAL_SECRET_KEY,
userEmail: 'demo@example.com',
});
await client.subscribe('chat/conv-7/messages');
client.transmit('chat/conv-7/messages', {
user: 'alice',
text: 'Hello everyone!',
});
// ... keep the process alive, then:
// client.destroy();
}
main();Next steps
- Connect from JavaScript - Browser + Node.js patterns with auth-provider tokens
- SDK catalog - Other
@cloudsignal/*packages (React UI, PWA, A2A, AI transport, MCP) - Token exchange API - Trade an identity provider token for MQTT credentials
- Connection parameters - Hosts, ports, and TLS reference