Introduction

Cariosan is a realtime chat SDK. It pairs a Go server with first-party TypeScript, React, React Native, and Go SDKs, and ships as a single Docker image you can deploy next to the rest of your stack — or you can let us host it for you.

Pick your path

Who this is for

Cariosan targets startups with customer-to-customer chat needs — marketplaces, on-demand services, edtech, healthtech — that need reliable chat without paying per-MAU SaaS fees, plus teams that need data residency for regulated content. It is Indonesian-first by origin, but the implementation is universally applicable.

• Startups with customer-to-customer chat needs — marketplaces, on-demand services, edtech, healthtech. You need reliable chat but don't want a $2k/month Stream Chat bill or opaque pricing tied to monthly active users.
• Teams that need data residency — health data, financial conversations, anything regulated. Cariosan's Postgres, Redis, and object store all run under your control.
• Indonesian-first products — the project is built around Southeast Asian market realities (flaky mobile networks, limited device storage), though nothing here is Indonesia-specific in the implementation.

What you get

Cariosan ships as a single Go binary plus thin client SDKs. The server exposes both REST and WebSocket transports for messaging, presence, typing, read & delivery receipts, reactions, quoted replies, @-mentions, full-text search, and member management.

# Pull and run the server image
docker run -p 8080:8080 ghcr.io/cariosan/server:latest

Out of the box you get the following first-party SDKs and integrations:

• REST API + WebSocket gateway for messaging, presence, typing, receipts, reactions, search, and member management — including group channels with avatars and enforced admin/member roles.
• TypeScript SDK (@cariosan/client) for browsers, Node, and React Native.
• React component library (@cariosan/react) with ChatProvider, MessageList, MessageInput, and related hooks.
• React Native UI kit (@cariosan/react-native) — native MessageList, MessageInput, ChannelList, and presence/typing components on the same headless core.
• Go server SDK (cariosan-go) for your backend to manage users, channels, and webhooks.
• Push notifications (FCM, bring your own Firebase project) — built in and privacy-first; off until you configure credentials.
• Automatic moderation (wordlists, link/phone/flood filters, plus user blocks & mutes) — opt-in per workspace, no AI, no extra cost.
• Signed webhooks for every event consumers care about (new messages, channel creation, member changes, moderation actions).
• Presigned S3 uploads so image and file attachments never proxy through the server.

What's intentionally out of scope

Cariosan is designed to be boring and maintainable. It deliberately ships without features that would either dilute focus or commit us to expensive infrastructure we can't reliably host. These are not included:

• Threads (a separate threaded-conversation pane à la Slack — quoted replies are supported)
• End-to-end encryption
• Voice / video

The opinionated "what we will not add" stance is part of the design — it keeps the surface area small enough for one-person operations. An earlier version of this list also excluded reactions, replies, per-message receipts, and push — those have since shipped; see the changelog.

Where to go next

If you haven't run Cariosan yet, head to the quick start — it walks through bootstrapping a workspace, issuing your first user token, and sending a message from the React SDK in under five minutes.

import { Cariosan } from "@cariosan/client";
 
const client = new Cariosan({
  apiUrl: "https://chat.example.com",
  token: tokenFromBackend, // issued by your Go backend, see the quick start
});
await client.connect();

• Follow the quick start to get a running Cariosan and send your first message.
• Read the concepts to understand the data model.
• Browse the REST API reference and WebSocket protocol.