Getting Started

Centrifugo is an open-source real-time messaging server that delivers messages to browser, mobile, and server-side clients over WebSocket, SSE, HTTP-streaming, and WebTransport. It is designed for high-throughput push scenarios: live feeds, notifications, chat, collaborative editing, and multiplayer games.

With Centrifugo on OSC you get a managed instance running in minutes, without managing infrastructure or tuning server configuration.

Prerequisites

  • An OSC account. Sign up here.
  • Your application backend (the system that publishes messages to Centrifugo). This can be any language — Centrifugo exposes an HTTP/gRPC publish API.

Create a Centrifugo instance

Navigate to Centrifugo, click Create centrifugo, and fill in:

Field Required Description
name Yes Unique name for this instance.
TokenHmacSecretKey Yes Secret key used to sign JWT tokens for client authentication. Keep this secret — your backend uses it to generate connection tokens for users.
AdminPassword Yes Password for the built-in admin web UI.
ApiKey No API key for the HTTP/gRPC publish API. If set, your backend must include this key in publish requests. Recommended for production.
RedisUrl No Redis/Valkey connection URL (e.g. redis://:password@host:6379). Enables horizontal scaling — multiple Centrifugo nodes share state via Redis. Connect to a Valkey instance on OSC.

Click Create. Once the instance is running, you'll see the public URL in the dashboard.

Default admin credentials

Interface URL Credential
Admin web UI https://{name}.centrifugal-centrifugo.auto.prod.osaas.io/ Username: (none), Password: your AdminPassword

Visit the admin UI to monitor channels, active connections, and message history.

Connecting clients

Centrifugo clients connect over WebSocket. The official client libraries are available for JavaScript, React Native, Go, Python, Swift, Dart, and more.

JavaScript (browser) example

Install the client:

npm install centrifuge

Your backend generates a JWT connection token signed with TokenHmacSecretKey:

// Backend (Node.js) — generate a connection token
const jwt = require('jsonwebtoken');
const token = jwt.sign(
  { sub: 'user123', exp: Math.floor(Date.now() / 1000) + 3600 },
  process.env.CENTRIFUGO_TOKEN_SECRET
);

Client-side connection:

import { Centrifuge } from 'centrifuge';

const client = new Centrifuge('wss://mycentrifugo.centrifugal-centrifugo.auto.prod.osaas.io/connection/websocket', {
  token: '<token-from-backend>'
});

const sub = client.newSubscription('news');
sub.on('publication', (ctx) => console.log(ctx.data));
sub.subscribe();
client.connect();

Publishing messages from your backend

Use the HTTP API (set ApiKey first):

curl -X POST https://mycentrifugo.centrifugal-centrifugo.auto.prod.osaas.io/api/publish \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"channel": "news", "data": {"text": "Breaking news!"}}'

Scaling with Valkey

To run multiple Centrifugo nodes (or add resilience), attach a Valkey instance:

  1. Create a Valkey instance on OSC.
  2. Copy its connection URL (format: redis://:password@host:6379).
  3. Set the RedisUrl field when creating (or updating) the Centrifugo instance.

All nodes share channel presence and message history via Valkey, enabling horizontal scaling.

CLI usage

osc create centrifugal-centrifugo mycentrifugo \
  -o TokenHmacSecretKey="{{secrets.centrifugo-token-secret}}" \
  -o AdminPassword="{{secrets.centrifugo-admin-pw}}" \
  -o ApiKey="{{secrets.centrifugo-api-key}}"

Resources