CatRealm Self-Hosted Server

Welcome to the CatRealm self-hosting documentation. Get your own CatRealm chat server running in minutes — on Windows, Linux, or through a Pterodactyl panel.

CatRealm is an open-source, self-hostable chat platform with text channels, voice chat, roles, permissions, and more. These docs cover everything you need to deploy and configure your own instance.

Dependencies

CatRealm requires very few dependencies to run:

OS Support

Windows Server

The easiest way to get started on Windows — no terminal required.

Manual Install

git clone https://github.com/VanillaChan6571/CatRealm-SelfHostable-Server.git
cd CatRealm-SelfHostable-Server

Linux Server

Run CatRealm on any modern Linux distribution.

Auto Installer

The fastest way to install CatRealm on Linux is the hosted auto-installer:

bash <(curl -fsSL https://raw.githubusercontent.com/VanillaChan6571/CatRealm-SelfHostable-Server/refs/heads/main/catrealm-auto-installer.sh)

Manual Install

git clone https://github.com/VanillaChan6571/CatRealm-SelfHostable-Server.git
cd CatRealm-SelfHostable-Server

chmod +x Start.sh

./Start.sh

nano .env

Manual Installation

If you prefer to skip the launcher scripts:

npm install --omit=dev
cp .env.example .env
nano .env          # edit your configuration
node src/index.js  # start the server

Running with PM2 (Production)

For a persistent, production-grade setup, use PM2:

# Install PM2 globally
npm install -g pm2

# Start CatRealm
pm2 start src/index.js --name catrealm

# Auto-start on system reboot
pm2 startup
pm2 save

Pterodactyl Egg

CatRealm has an official Pterodactyl egg for easy panel-based hosting.

Hoster Setup

https://raw.githubusercontent.com/VanillaChan6571/CatRealm-SelfHostable-Server/main/pterodactyl-egg/egg-cat-realm-server.json

Hosting Features

One CatRealm installation can host multiple independent realms, run first-party bot plugins, and relay mention notifications to central-account mobile users.

Multi-Realm Hosting Optional

Multi-realm mode runs several isolated realms from one installation. Each realm has its own HTTP/WebSocket port, SQLite database, users, roles, messages, and secrets. The realms share the repository, dependencies, uploads, TLS certificate, and one LiveKit media service.

MULTI_REALM=true

{
  "version": 1,
  "realms": [
    { "port": 40500, "name": "Main Realm", "dbFile": "40500.db", "enabled": true },
    { "port": 40501, "name": "Second Realm", "dbFile": "40501.db", "enabled": true }
  ]
}

Bots & Plugins

CatRealm supports token bots that run anywhere and plugin bots that the server runs as child processes. Both are real realm members: assign roles to grant server permissions, while each user separately approves requested consent scopes such as profile access, mentions, and Bot DMs.

{
  "name": "greeter",
  "username": "GreeterBot",
  "entry": "index.js",
  "scopes": ["interactions", "mentions"],
  "commands": [
    { "name": "greet", "description": "Say hello", "options": [] }
  ]
}

If a plugin has uninstalled npm dependencies, CatRealm waits for owner approval. Approve it from Realm Settings → Bots or with botinstall <name> in the server console.

Push Notification Relay Central Accounts

Self-hosted realms can relay channel @mention notifications to CatRealm mobile devices. This only applies to users signed in with a central CatRealm account; local-only accounts do not have central push tokens.

Generate a secret, add it to .env, and restart. The realm registers itself automatically with the central service using its public SERVER_URL.

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

PUSH_RELAY_SECRET=paste-your-generated-secret
AUTH_SERVER_URL=https://auth.catrealm.app

ENV Overview

CatRealm is configured through environment variables in your .env file. Below are the common settings from the current server template, including the latest hosting and media options.

Server

Core settings that define how your server presents itself.

# ── Server ────────────────────────────────────────────────────
PORT=40500
SERVER_NAME=My CatRealm Server
SERVER_DESCRIPTION=A cozy self-hosted realm

Security

Authentication and encryption settings.

# ── Security ──────────────────────────────────────────────────
JWT_SECRET=change-this-to-a-long-random-string
SECURE_MODE=1
# SECURE_MODE_KEY=    # auto-generated when SECURE_MODE=1

Registration

Control whether new users can sign up on your server.

# ── Registration ──────────────────────────────────────────────
REGISTRATION_OPEN=true

Database

CatRealm uses SQLite — no external database server needed.

# ── Database ──────────────────────────────────────────────────
DB_PATH=./data/catrealm.db

Hosting Features

# Optional hosting features
MULTI_REALM=false
BOTS_PLUGINS_ENABLED=true
# PUSH_RELAY_SECRET=generate-a-random-32-byte-secret

CORS

Controls which origins can make requests to your server's API.

# ── CORS ──────────────────────────────────────────────────────
CLIENT_URL=*
# Production example:
# CLIENT_URL=https://app.example.com

Uploads Directory

Paths where user-uploaded files are stored on disk.

# ── Uploads ───────────────────────────────────────────────────
UPLOADS_DIR=./data/uploads
UGC_IMAGES_DIR=./data/ugc/images

Default Local Avatar Image Local Accounts Only

Set a default avatar URL for newly created local accounts. If not set, users will have no avatar until they upload one.

# Optional: default avatar for new local accounts
DEFAULT_AVATAR_URL=https://cdn.example.com/default-avatar.png

Block Generic Usernames Decentral Only

Prevent users from registering with reserved or common usernames (e.g. "admin", "moderator"). Only applies to local (decentral) accounts.

# Block specific usernames from registration (local/decentral accounts only)
BLOCKED_USERNAMES=admin,moderator,official,support
# Or use a file (one username per line):
BLOCKED_USERNAMES_FILE=./blocked-usernames.txt

Server Mode

Controls what type of accounts are allowed to join your server.

# Server mode (optional — runtime defaults to decentral_only)
# SERVER_MODE=mixed            # both local and central
# SERVER_MODE=decentral_only   # local accounts only (default)
# SERVER_MODE=central_only     # central accounts only

# Required for mixed/central_only:
# AUTH_SERVER_URL=https://auth.catrealm.app

Media Limits

Configure upload size limits for different types of media.

# ── Media Limits ──────────────────────────────────────────────
MEDIA_MAX_MB=20
COMPRESS_MEDIA=0
LEVEL_OF_COMPRESSION=6
AVATAR_MAX_MB=10
MAX_PINS=300
MENTION_ALIAS=@everyone

Voice & Theater Media

Current CatRealm clients use LiveKit for voice, camera, screen sharing, and Theater. Use bundled LiveKit, connect an external LiveKit deployment, or enable the authenticated central fallback.

# Bundled LiveKit example
HOST_LIVEKIT_MEDIA=true
LIVEKIT_PUBLIC_HOST=media.example.com
LIVEKIT_RTC_TCP_PORT=7881
LIVEKIT_RTC_UDP_PORT_START=50000
LIVEKIT_RTC_UDP_PORT_END=50100

Auto Update

When enabled, the startup launcher will pull the latest changes from your configured Git repository before starting the server.

# ── Auto Update ───────────────────────────────────────────────
AUTO_UPDATE=true
GIT_REPO=https://github.com/VanillaChan6571/CatRealm-SelfHostable-Server.git
GIT_BRANCH=main

SSL / HTTPS Guide

HTTPS is required to use the CatRealm web app from any device other than localhost. CatRealm has built-in SSL support powered by Let's Encrypt — no separate reverse proxy needed.

Auto SSL via Cloudflare DNS Recommended

This method uses the DNS-01 ACME challenge, which means port 80 does not need to be open. It's ideal for servers behind firewalls or NAT. You just need a domain pointed to Cloudflare and a Cloudflare API token.

1

Point your domain to Cloudflare

Ensure your domain (e.g. chat.example.com) has an A record in Cloudflare DNS pointing to your server's public IP. Use DNS only (gray cloud) for any hostname that carries LiveKit media ports.

2

Create a Cloudflare API token

Follow the steps below in the Cloudflare dashboard:

1 Click your profile icon in the top-right corner

2 Select API Tokens from the left sidebar

3 Find Edit zone DNS and click Use template

4 Leave permissions as-is, then click Continue to summary

5 Review the summary and click Create Token

6 Copy your token — it will not be shown again

⚠️

Save the token immediately. Cloudflare will not show it again after you leave the page. If you lose it, you'll need to delete it and create a new one.

3

Add SSL variables to your .env

# Auto-SSL via Cloudflare DNS-01
SSL_DOMAIN=chat.example.com
SSL_EMAIL=[email protected]
SSL_DNS_PROVIDER=cloudflare
SSL_DNS_API_TOKEN=your-cloudflare-api-token

4

Restart the server

CatRealm will automatically request a certificate from Let's Encrypt using the Cloudflare DNS challenge. Once issued, the server will serve HTTPS on port 443 and HTTP on your configured PORT.

SSL via Certbot

If you prefer to manage certificates manually, you can obtain them with Certbot and provide the paths to CatRealm.

sudo apt update
sudo apt install -y certbot

sudo certbot certonly --standalone -d chat.example.com --email [email protected] --agree-tos

# Manual certificate paths
SSL_CERT_PATH=/etc/letsencrypt/live/chat.example.com/fullchain.pem
SSL_KEY_PATH=/etc/letsencrypt/live/chat.example.com/privkey.pem

# /etc/letsencrypt/renewal-hooks/post/catrealm.sh
#!/bin/bash
pm2 restart catrealm

chmod +x /etc/letsencrypt/renewal-hooks/post/catrealm.sh

Advanced

Advanced configuration for power users and production deployments.

Connect External LiveKit

Use an external LiveKit deployment when media should run on separate infrastructure. CatRealm keeps the API secret server-side and mints short-lived participant tokens for clients.

MEDIA_LIVEKIT_ENABLED=true
MEDIA_LIVEKIT_URL=http://127.0.0.1:7880
MEDIA_LIVEKIT_PUBLIC_WS_URL=wss://media.example.com
MEDIA_LIVEKIT_API_KEY=your-api-key
MEDIA_LIVEKIT_API_SECRET=your-api-secret
MEDIA_TOKEN_TTL_SECONDS=600

Firewall Checklist

• Expose the public secure WebSocket endpoint used for LiveKit signaling.
• Expose LiveKit's configured TCP media fallback port.
• Expose the full configured UDP media range.
• Keep the API secret on the CatRealm server only.