Service: Centrifugo - EyevinnOSC/community GitHub Wiki
Centrifugo (serviceId centrifugal-centrifugo) is an open-source (Apache-2.0) real-time messaging server that delivers messages to browser, mobile and server-side clients over WebSocket, SSE, HTTP-streaming and WebTransport. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance.
- Push messages to connected clients in real time: live feeds, notifications, chat, collaborative editing, multiplayer games.
- Authenticate clients with JWT connection tokens signed with a shared HMAC secret.
- Accept publish requests from any backend over an HTTP/gRPC server API protected by an API key.
- Provide an embedded admin web UI for monitoring channels and connections.
- Scale horizontally across several Centrifugo nodes by connecting a Redis-compatible store such as Valkey.
Find the id with list-available-services, read the options with get-service-schema, then call create-service-instance with serviceId: "centrifugal-centrifugo". The instance name must be alphanumeric and at most 20 characters. No other OSC service is required; add a Valkey instance (valkey-io-valkey) only if you want horizontal scaling, and confirm it is running before creating Centrifugo.
{
"name": "mycentrifugo",
"TokenHmacSecretKey": "{{secrets.centrifugotoken}}",
"AdminPassword": "{{secrets.centrifugoadmin}}",
"ApiKey": "{{secrets.centrifugoapikey}}"
}Create the secrets first with create-service-secret (serviceId centrifugal-centrifugo, name, value). Use wait-for-service-ready or get-instance-status to confirm the instance is running, and describe-service-instance to read its URL and any generated credentials.
| Option | Required | Type | Meaning |
|---|---|---|---|
| name | Yes | string | Name of the instance. Alphanumeric, at most 20 characters. |
| TokenHmacSecretKey | Yes | string, sensitive | Secret key used to verify the HMAC signature of the JWT tokens that clients present when connecting. Your backend signs connection tokens with the same key. Can be generated by the system if left empty. |
| AdminPassword | Yes | string, sensitive | Password for the embedded admin web UI. Can be generated by the system if left empty. |
| ApiKey | No | string, sensitive | Key that authenticates requests to the HTTP and gRPC server API (for example publishing). Your backend sends it in the X-API-Key header. Recommended for production. |
| RedisUrl | No | string, sensitive | Connection URL of a Redis or Redis-compatible server (Redis, Redis Cluster, Valkey, KeyDB, DragonflyDB), for example redis://:password@host:6379. When set, multiple Centrifugo instances share state and can scale horizontally. |
| AllowedOrigins | No | string | Origins allowed to connect from browsers. The catalog gives no further description or format. |
TokenHmacSecretKey, AdminPassword, ApiKey and RedisUrl are sensitive: store them as service secrets and pass them as {{secrets.NAME}}, which only works as the entire field value. Overwriting a secret does not restart a running instance.
The admin web UI is served at the instance URL (https://<name>.centrifugal-centrifugo.auto.prod-se.osaas.io/). There is no username; sign in with the AdminPassword. Use it to monitor channels, active connections and message history.
Official client libraries exist for JavaScript, React Native, Go, Python, Swift, Dart and more. Your backend generates a JWT connection token signed with TokenHmacSecretKey:
// Backend (Node.js)
const jwt = require('jsonwebtoken');
const token = jwt.sign(
{ sub: 'user123', exp: Math.floor(Date.now() / 1000) + 3600 },
process.env.CENTRIFUGO_TOKEN_SECRET
);// Browser
import { Centrifuge } from 'centrifuge';
const client = new Centrifuge('wss://mycentrifugo.centrifugal-centrifugo.auto.prod-se.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();Use the HTTP API with the ApiKey you configured:
curl -X POST https://mycentrifugo.centrifugal-centrifugo.auto.prod-se.osaas.io/api/publish \
-H "Content-Type: application/json" \
-H "X-API-Key: your-api-key" \
-d '{"channel": "news", "data": {"text": "Breaking news!"}}'- Create a Valkey instance and wait until it is running.
- Build its connection URL (format
redis://:password@host:6379) from the address, port and password indescribe-service-instance. - Set
RedisUrl(as a secret reference) when creating, or withupdate-service-instanceon, the Centrifugo instance.
All nodes then share channel presence and message history through Valkey.
osc create centrifugal-centrifugo mycentrifugo \
-o TokenHmacSecretKey="{{secrets.centrifugo-token-secret}}" \
-o AdminPassword="{{secrets.centrifugo-admin-pw}}" \
-o ApiKey="{{secrets.centrifugo-api-key}}"