Settings

Relay includes a full in-app Settings area for both end users and instance admins. This page focuses on what each Settings section does. For the Relay-specific feature list itself, see Relay Features.

Use the Search settings field at the top of the Settings window to search across available controls and jump directly to a matching setting. Results are grouped by section and open the relevant control when selected.

Settings sections at a glance

Section	What it controls	Notes
General	App integration and settings synchronization	Available to signed-in users
Chat	Messages, previews, composer behavior, code blocks, and message bubbles	User preference section
Interface	Visual aids, message input, sidebar organization, and image viewer behavior	User preference section
Themes	Built-in themes, theme import/export, custom CSS	Relay extends upstream theme handling
Aliases	Custom IRC command shortcuts	Relay-specific feature
Uploads	Per-user uploads, shortened URLs, and shared message links	Private authenticated instances; available features depend on server settings
Experimental DCC files	Received DCC files, expiry information, and deletion	Private authenticated instances when enabled by an admin
Short Links	Per-user short link review, sorting, and deletion	Available when the link shortener is enabled on non-public instances
Security & sessions	Password, passkeys, authenticator app, recovery codes, active sessions, and account security	Private authenticated instances only
Notifications	Push, browser, and in-window notification behavior, alert duration, reply/reaction alerts, highlight keywords	Per-user notification preferences
Profile	Profile metadata, avatar, and call identity	Profile support depends on instance and integration settings
Stats	Personal activity totals, message graphs, and storage usage	Relay-specific visibility into usage
Administration	Server, Storage, Media & files, Authentication, Integrations, Branding, Users, and Operations	Admin accounts only

General

The General section covers client behavior that does not fit elsewhere:

• Add Relay to the home screen as a native-style web app on supported browsers.
• Register Relay to open irc:// links directly from the browser.
• Synchronize settings between clients when settings sync is enabled.

Chat

The Chat section controls how chat content is presented:

• Show or hide the server MOTD.
• Switch between 12-hour and 24-hour-style timestamp behavior, with an option to include seconds.
• Control link preview expansion for media and websites.
• Show inline video embeds when the instance administrator enables them, independently of other link previews.
• Show messages in optional theme-aware speech bubbles with sender-aware grouping, reaction placement, and reply context. Enable bubbles on all devices or limit them to mobile-sized screens (768 pixels wide or smaller).
• Enable the Activity feed and choose Off, All buffers, Favorite buffers, or Custom buffers for broad activity. Custom buffers can be selected as exact channels and private conversations in a searchable picker with selected-only filtering and select-all/clear-matches actions. Directed activity can be enabled separately to include mentions and replies. Enable Show activity in the top pane to keep the feed above the current conversation. The Activity view supports loading older entries and clicking an entry to return to its original message. Activity is available when structured message storage is enabled; muted buffers and the partyline are not eligible sources.
• Choose how status messages are shown: expanded, condensed, or hidden.
• Use the text styling toolbar to preview and apply IRC-compatible formatting and colors while composing messages.
• Enable syntax highlighting for labeled fenced code blocks and choose a Prism theme for supported languages.
• Enable autocomplete for nicknames, channels, and commands, and choose what Relay adds after an autocompleted nickname.
• Toggle typing indicators and whether your typing state is sent to others.
• Configure an automatic away message when the instance is private.

Relay's autocomplete covers nicknames, channels, and commands directly from the chat input. Typing / opens command suggestions with usage and descriptions, including commands that are unavailable in the current context. Press Tab to complete the current match, press it again to cycle forward through suggestions, or use Shift+Tab to cycle backward.

Interface

The Interface section controls visual aids and sidebar organization:

• Enable colored nicknames and online status indicators for private queries.
• Hide the nickname badge beside the message input across all themes, or restore the selected theme's default visibility.
• Hide favorite channels when networks are collapsed while keeping them visible when networks are expanded.
• Enable nested sub-channels in the sidebar. Choose whether : and - separators define parent and child channel relationships, and whether child entries use short or full channel names.
• Choose whether the image viewer inverts the mouse-wheel zoom direction.

Themes

The Themes section lets users personalize Relay's look and feel:

• Open the searchable theme selector to browse Relay's large collection of built-in themes by category, filter by name or category, preview candidates, and apply a selection.
• Export the active theme as a CSS file.
• Import a CSS file as a new selectable theme.
• Add custom CSS overrides directly in the browser.

This is one of Relay's most visible customization features, especially for communities that want custom branding without rebuilding the client.

Aliases

The Aliases section manages custom IRC command shortcuts.

• Create short commands such as /shrug or /j that expand into longer IRC commands.
• Use positional variables like $1 and $2, $* for all arguments, and $channel for the current channel name.
• Edit or delete aliases from the same screen.

Relay also supports alias expansion in chat input and command autocomplete.

Uploads

The Uploads section is the user-facing side of Relay's file handling:

• Remove image metadata on-device before uploading when desired. Relay also sanitizes supported images on the server before storing or forwarding them.
• Review previously uploaded files.
• Sort uploads and delete individual items.

Upload expiration is now controlled by the instance admin as a server-wide setting rather than as a per-user preference. If the admin disables uploads or the instance is running in public mode with upload restrictions, some options may be limited.

Shared messages

On private instances, the Shared Messages tab under Settings > Uploads lists the message links you created. For each share, you can open the read-only page, copy its link, and delete it. Shares are paginated, show their creation and expiration times, and follow the server-wide upload expiration policy. Deleting a share immediately invalidates its link and cannot be undone.

In the standalone desktop client, the Uploads section also lets you choose between Relay storage and Catbox. Catbox returns a public shareable link, and Catbox-hosted files do not appear in Relay's upload manager; use the links in chat to access them. The browser client and mobile PWA continue using Relay's built-in upload storage.

Experimental DCC files

The Experimental DCC files section lists files received through Relay's experimental DCC support. Incoming offers require explicit approval before Relay downloads them. Received files are private to your account, show their expiration time, and can be deleted from this section.

Short Links

The Short Links section lets users manage links created by Relay's built-in link shortener:

• Review the short links you have created.
• Sort links by short code, creation time, or expiration time.
• Open the short link directly to verify the redirect target.
• Delete links you no longer want to keep around.

This section is available when the short-link feature is enabled and the instance is not running in public mode.

Security & sessions

The Security & sessions section provides account security management:

• Change your password.
• Review current and other signed-in sessions and revoke sessions you no longer use.
• View, name, register, and remove hardware keys and passkeys.
• Enroll a standard TOTP authenticator app by scanning a QR code or entering the setup key manually.
• Save the eight single-use recovery codes shown during authenticator enrollment.

Security keys and platform passkeys can provide passwordless sign-in when two-step sign-in is optional, or complete the second step after a local password. Enrolling an authenticator app protects that account's future local password logins even when the instance does not enforce two-step sign-in. OIDC sign-ins continue to use the identity provider's authentication policy.

Notifications

The Notifications section controls how Relay gets your attention:

• Subscribe to push notifications.
• Enable browser notifications and notification sound.
• Enable in-window notifications in the active Relay client. Choose a device-local duration from 1 to 3600 seconds (5 seconds by default). Click an alert to jump to its channel; message and reaction alerts also focus and briefly pulse the related message when it is available.
• Choose from the expanded set of bundled notification sounds and preview the selected sound.
• Upload a custom MP3, WAV, or Ogg/Opus notification sound up to 2 MB and 10 seconds when the instance is private and file uploads are enabled.

• Choose which message types can trigger alerts.

  • mentions and custom highlights
  • private messages
  • replies to your messages
  • reactions to your messages

• Choose whether all messages can trigger notifications when broader alerts are desired.

• Enable or disable notifications for all messages in an individual channel or conversation from its context menu.
• Define custom highlight words.
• Define highlight exceptions to reduce noise.

These settings apply to browser notifications, in-window notifications, and push notifications, subject to Relay's usual mute and freshness checks. The preview control enables audio playback in browsers and mobile WebViews; operating-system push notifications use the platform's own notification sound. When an IRC network supports IRCv3 invite-notify, Relay can also notify you when someone invites you to a channel. Typing notifications are configured in Chat, while message alerts live here.

Profile

The Profile section combines profile metadata with avatar and call identity settings:

• Set a user-visible display name.
• Add a homepage link to your profile.
• Choose a nickname or identity color.
• Set a custom status that is separate from Relay's online and away indicators.
• Upload, change, or remove a global persistent profile avatar when the instance enables avatars.
• Set the display name used in Jitsi voice/video calls when that integration is enabled.

On IRC servers advertising draft/metadata-2, Relay synchronizes these profile values with IRC users. On servers without that capability, Relay still saves and displays the values locally, but they are not shared over IRC. Avatar uploads use the existing upload UI and are available only when an administrator enables them on a non-public instance. The administrator also sets the maximum avatar file size. Custom status remains separate from Relay's online and away indicators.

Sign out from the prominent control in the Settings header. Security keys, password changes, and session management are available in Security & sessions.

Stats

The Stats section surfaces usage information that is not documented elsewhere in the current docs:

• Personal totals such as connected networks, joined channels, messages logged, and storage used.
• A graph of messages logged over the last 7 days.
• Server-wide totals such as total networks and total channels across all users.
• Storage-by-user reporting, including upload and log usage.
• A manual refresh action for on-demand recalculation.

Large instances may take a little longer to compute storage statistics because Relay scans cached usage data and user storage on demand.

Administration

The Administration area is Relay's server-side control panel for administrators. It is organized into Server, Storage, Media & files, Authentication, Integrations, Branding, Operations, and Users sections so related controls are easier to find.

Server

Admins can manage server-wide behavior without editing config files manually:

• Allow or disable self-registration and optionally cap the number of accounts created through it. Administrators can still create users after the cap is reached.
• Enable or disable network groups in the sidebar.
• Set maximum stored channel history.
• Enable or disable the local /relaystats command and customize its output template with supported placeholders such as $nick, $usernetworks, $userchannels, $messageslogged, $storagebytes, $databasebytes, $uptime, $relayversion, $os, and $go.

The /relaystats command renders its output only inside Relay and never sends it to an IRC network. Some server-level changes require a server restart to take effect. For deployments that must expose only a preconfigured network, lockNetwork: true in config.yaml prevents users from changing the network's connection and proxy settings; public mode applies the same boundary automatically and also hides the configured transport credentials.

For settings that require a reload, Relay shows explicit Apply Changes and Cancel controls so admins can commit pending config updates or discard them directly from the web UI.

Storage

The Storage section controls message history:

• Choose the primary message-history backend: SQLite, PostgreSQL, or disabled.
• Enable or disable plain-text message logs separately.
• Configure the PostgreSQL connection string and connection-pool limits when PostgreSQL is selected.
• Configure optional message retention with storagePolicy in config.yaml, including the maximum age and whether status messages or all messages are deleted. Run relay storage clean for an immediate cleanup.

SQLite is the default message-history backend. The PostgreSQL connection string is stored server-side and is never returned to the browser. Changing the backend or PostgreSQL connection settings requires a server restart.

Media & files

The Media & files section controls server-side media and file behavior:

• Enable persistent user avatars and set the maximum avatar size.
• Enable link prefetch and URL previews, control inline media previews and click-to-play video embeds, and choose whether prefetched media is stored on the server.
• Set the maximum prefetch image size.
• Enable file uploads, set the maximum upload size, and set the server-wide upload expiration default.
• Enable experimental DCC file receiving and configure its listen and advertised addresses, file size, concurrent transfer, retention, minimum free-space, and download-URL settings.

Inline video embeds require link prefetching and inline media previews to remain enabled. Some media and file settings require a server restart.

Authentication

Relay's Authentication section includes local two-step sign-in, email-backed registration, and OpenID Connect single sign-on:

• Require a registered security key or authenticator code during fresh local password sign-ins. Users without a factor must enroll before entering chat.
• Enable SMTP and use it for registration email verification.
• Enable single sign-on, then configure the OIDC issuer URL, client ID, client secret, requested scopes, and username claim path.

Users must already have a matching Relay account for OIDC sign-in to succeed. A provider-specific username claim such as relay_username is recommended. Use Relay's OIDC callback URL from this section as the provider redirect URI. Relay does not add its own second-factor challenge to OIDC sign-ins, so configure the desired MFA policy at the identity provider.

Integrations

Relay's Integrations section includes optional services and instance-wide features:

• Configure Jitsi Meet voice/video calling and its server URL.
• Enable the KLIPY GIF picker and set its server-side API key.
• Enable the internal #partyline channel and choose its synthetic network and channel names.
• Enable the built-in link shortener, set its threshold, expiration, path prefix, and optional base URL. Users manage their own links in the Short Links section.

Partyline is off by default. When enabled, it creates a synthetic channel for local users on the same instance; its history remains tied to a stable internal network ID so earlier messages still load after a restart. The link shortener stores redirect data server-side so links can resolve without the creating user being known at redirect time.

Branding

Relay's Branding section can expose custom artwork:

• Choose the default theme for the instance.
• Display or hide a branding logo for authentication screens and the sidebar.
• Set primary and optional inverted logo URLs, or upload logo assets when file uploads are enabled.

If no inverted logo is provided, Relay falls back to the primary logo URL automatically.

Operations

The Operations section can restart the Relay server from the web UI. This disconnects clients; a process manager must restart the server.

Users

The Users section lets admins view users, grant or remove admin access, enable or disable per-user logging, reset passwords, and add new users.

Related pages

• See Relay Features for the high-level list of Relay-specific features.
• See Installation for Docker, Compose, and first-run setup.
• See Known Limitations for ZNC and soju behavior around replies and reactions.