About Open Relay Portal

A complete guide to using Open Relay Portal — your secure, self-hosted gateway for remote infrastructure access, live streaming, and community communication.

Overview

Open Relay Portal is a secure, authenticated web gateway for managing home and cloud infrastructure remotely. It consolidates remote access, process management, live streaming, and team communication into a single web interface accessible from any browser.

View on GitHub — Open Source (AGPL-3.0)

Roles & Permissions

Access is controlled by a role hierarchy. Higher roles inherit all permissions from lower roles.

Dashboard

The Dashboard is your home screen after login. It shows live stats and provides quick access to all features.

Stats Overview

The top of the dashboard shows real-time statistics:

• Live Streams — Number of currently broadcasting streams
• Online Users — Users currently connected to the portal
• Total Services — Number of configured services (admin only)
• Active Services — Running managed processes (admin only)

Stats auto-refresh every 30 seconds.

Dashboard Tabs

Activity Feed

The sidebar shows recent portal activity (stream events, user logins, etc.) with live-updating timestamps and fade effects for older entries.

Quick Actions

The sidebar includes Quick Actions for fast access to common tasks:

• Refresh Resources — One-click refresh of all dashboard data: connections, streams, stats, and services
• File Manager — Quick link to the Remote Files (SFTP) interface for browsing files on your remote servers

The Administration section (admin only) provides links to Manage Users, Invite Code, View Logs, and the Admin Panel.

User Connections

Connections are personal remote access points to your servers, databases, and network services. Each user manages their own connections independently.

Creating a Connection

From the My Connections tab, use the Quick Add bar to create a connection from a preset (SSH, VNC, RDP, MySQL, PostgreSQL, Proxmox, HTTP Proxy), or click Add Connection to fill in:

• Name — A descriptive label (e.g., "Home Server SSH")
• Type — The protocol to use (see table below)
• Host — IP address or hostname of the target
• Port — Service port (defaults vary by type)
• Username — Login username (for SSH/VNC connections)
• Auth Method — Password or SSH key (for SSH connections)

When you select a preset, documentation links appear below the dropdown — one linking to the software's official documentation and one linking to the Portal Setup Guide for that connection type.

Web UI connections (HTTP Proxy, Home Assistant, Grafana, Plex, and 40+ other types) open in Portal's embedded browser with tabbed browsing, multi-site navigation, and full navigation controls (back/forward, address bar, refresh). Browser-mode connections can navigate to any website through the proxy. Each user gets a default "Web Browser" connection with DuckDuckGo as the homepage. All traffic is reverse-proxied through Portal, so remote web interfaces are never exposed directly. Connection IDs use opaque tokens for security. HTTPS is enforced for all proxied connections via TLS.

Connection Types

Open Relay Portal supports 75 connection types out of the box, covering remote access, web panels, databases, media servers, dev tools, monitoring, automation, file/photo management, security, and networking. The most common types are listed below — see the Guides page for detailed setup instructions for each connection type.

Remote Access

Web Panels

Databases

Dev Tools & Monitoring

Media & Game Servers

Network & Tunneling

Connecting

Click the Connect button on any connection to open the appropriate viewer in a new window. For SSH connections, you will be prompted for credentials (password or key-based authentication).

For HTTP/HTTPS connections (web panels, dev tools, and other web services), the connection opens in Portal's embedded browser with navigation controls (back, forward, refresh), an address bar showing the proxied path, and TLS enforcement for secure communication with the backend service.

For tunnel-type connections (database, redis, tcp_tunnel), the portal displays the host and port information for use with your local client software.

Pinning & Usage Tracking

Connections track usage automatically:

• Pin Connections — Click the pin icon to keep frequently used connections at the top of your list
• Usage Stats — Each connection shows when it was last used and total connection count
• Smart Sorting — Pinned connections appear first, then sorted by most recently used

Streaming

Open Relay Portal includes a full live streaming platform. Broadcast from OBS or any RTMP-capable encoder via secure RTMPS or standard RTMP with temporary publish tokens. Viewers can watch via the community Streams page.

Setting Up OBS

In OBS Studio, go to Settings → Stream and configure:

# Option 1: RTMPS (recommended, encrypted)
Service:  Custom
Server:   rtmps://stream.yourdomain.com:1936/live
Stream Key: live_xxxxxxxxxxxx  (your private stream key)

# Option 2: Plain RTMP (temporary token, enable RTMP on stream first)
Service:  Custom
Server:   rtmp://stream.yourdomain.com:1935/live
Stream Key: rtmp_xxxxxxxxxxxx  (generate from My Streams tab)

Stream Keys

Each user has two permanent stream keys and can generate temporary RTMP tokens:

Manage your stream keys and generate RTMP tokens from the My Streams tab on the Dashboard.

Streaming Features

• Dual Publishing — Publish via secure RTMPS (port 1936) or standard RTMP (port 1935) with temporary tokens
• Dynamic Thumbnails — Auto-generated preview images from your live stream, updated every 15 seconds
• Viewer Count — Real-time viewer count displayed on the stream page, polled every 10 seconds
• Quality Selector — Viewers can choose stream quality when available
• Public/Private Toggle — Control whether your stream appears on the community Streams page
• Popout Player — Watch streams in a floating overlay or separate window
• Stream Lifecycle — Live → Encoding → Offline: streams transition through an encoding state while VOD chunks are finalized and offloaded to SFTP, ensuring no recorded data is lost
• Standard RTMP with Temporary Tokens — Generate single-use publish tokens for plain RTMP when TLS is not available
• Multi-Platform Relay — Simultaneously relay your stream to Twitch, YouTube, Kick, other Portal instances, or any custom RTMP destination. Up to 10 relay targets per stream, with credentials encrypted at rest

Encoder Support

Community Chat

The Chat page provides real-time encrypted messaging for your team or community.

Channels

Chat is organized into channels. Default channels include #general, #random, and #help. Admins can create, rename, and delete custom channels.

Message Features

• Markdown — Use **bold**, *italic*, `code`, ~~strikethrough~~, and ||spoiler|| (click to reveal)
• Headers — Use # Heading, ## Subheading, and ### Small Heading for message structure
• @Mentions — Type @ to open an autocomplete dropdown filtered by your input. Select with arrow keys and Enter/Tab, or click a suggestion.
• Replies & Threads — Click the reply icon to respond to a message. Click any reply preview to open a thread panel showing the full reply chain.
• Emoji Reactions — React to any message with emoji. Right-click a message and choose "React" to pick an emoji, or click an existing reaction pill to toggle yours.
• Message Editing — Edit your own messages within 5 minutes of sending. Right-click and select "Edit" to modify inline. Edited messages show an (edited) indicator.
• Pinned Messages — Moderators and admins can pin important messages. A pinned banner at the top of chat shows the count and expands to reveal all pinned messages.
• Link Previews — URLs in messages automatically generate preview cards with title, description, and thumbnail from OpenGraph metadata.
• YouTube Embeds — YouTube links are automatically embedded as inline video players (privacy-enhanced mode via youtube-nocookie.com).
• Image Sharing — Upload images via the attachment button or paste from clipboard. Uploaded files are sanitized — only safe types render inline; HTML/JS/SVG are forced to download to prevent XSS.
• Anonymous Mode — Post messages without revealing your identity

Unread Badges

Channels with unread messages show a badge count in the sidebar. Badges update in real-time and clear automatically when you view the channel.

Profiles & Presence

Customize your chat presence with:

• Display Nickname — Set a custom name shown in chat and throughout the portal
• Avatar — Choose from a collection of avatar icons
• Status — Set your status to Online, Away, Busy, Do Not Disturb, or Offline
• Status Message — Add a custom status message visible to other users
• Auto-Presence — Status automatically updates to online when you connect, away after 5 minutes idle, and offline when you disconnect
• Last Seen — Offline users show "Last seen X ago" so you know when they were last active

Online Users

The right sidebar shows currently online users with their roles indicated by color and presence status indicators. Click a username to insert an @mention.

Voice Chat

Each chat channel supports live voice chat. Voice uses WebRTC for direct peer-to-peer audio — the server only relays connection setup, never processes or stores audio.

• Join/Leave — Click "Join Voice" in the channel header to start. Audio connects directly between participants.
• Mute/Deafen — Mute your microphone or deafen to silence all incoming audio. Controls appear in the voice bar.
• VAD Mode — Voice Activity Detection automatically transmits when you speak. Adjust sensitivity in voice settings.
• Push-to-Talk — Hold a key (default: Space) to transmit. Rebind the key in voice settings.
• Speaking Indicators — Users in voice show a green highlight when speaking, with mute/deafen icons in the user list.
• Watch Page — Voice chat is also available in the stream watch page sidebar for coordinated viewing.
• DM Voice — Start a voice call directly in any DM conversation (1:1 or group). Works the same as channel voice with all the same controls.

Direct Messages

Private conversations outside of public channels. Start a 1:1 chat or create a group DM with up to 10 participants.

Getting Started

Open a new conversation from the chat sidebar by clicking New Message, then search for users by username or nickname. Select one user for a 1:1 DM, or select multiple users (up to 10) for a group conversation.

DM Features

• Encrypted at Rest — All DM messages are encrypted with Fernet, same as channel messages. Content is never stored in plaintext.
• Real-Time Delivery — Messages arrive instantly via WebSocket. No polling or page refresh needed.
• Reactions — React to messages with emoji, just like in channels.
• Replies — Reply to a specific message to maintain context in a conversation.
• Editing — Edit your own messages within 5 minutes of sending. Edited messages show an (edited) indicator.
• Deletion — Delete your own messages. Admins can delete any message.
• Typing Indicators — See when other participants are typing in real time.
• Unread Badges — DM conversations with unread messages display a badge count in the sidebar, updating in real time.
• Mute Conversations — Mute noisy conversations to suppress notification badges without leaving the conversation.
• Offline Notifications — Missed messages are queued and surfaced via the notification bell when you come back online.

Group DMs

Group DMs support 2 to 10 participants. All members can add new participants to an existing group. The conversation name defaults to a comma-separated list of member names but can be renamed by any participant.

Message Search

Full-text search across all your channels and direct messages, powered by SQLite FTS5 for fast, relevant results.

Using Search

Open the search bar with Ctrl+K (or Cmd+K on macOS), or click the search icon in the chat header. Type your query and press Enter to see results.

Search Filters

Filters can be combined freely. For example: from:alice in:general has:image after:2026-02-01

Scope

By default, search covers all channels and DMs you have access to. Use the scope selector to narrow results:

• All — Search across all channels and DMs
• Channels — Only search public channel messages
• Direct Messages — Only search your private conversations

Navigating Results

Search results display the message text, author, channel or DM name, and timestamp. Click any result to jump directly to that message in its original context, with the message highlighted.

User Blocking

Block users to hide their messages and prevent DM communication.

• Hide Messages — Messages from blocked users are collapsed in chat channels. Click to optionally reveal.
• DM Prevention — Blocking is bidirectional for DMs — neither party can message the other while a block is active.
• Easy Management — Right-click any message to block/unblock the sender, or manage your block list via the REST API.
• Personal Preference — Blocking is per-user and does not require admin intervention. Admins cannot override personal blocks.

Polls

Create inline polls in any chat channel to gather opinions and make decisions collaboratively.

• Quick Creation — Click the poll button next to the emoji picker. Add a question, 2-10 options, and optional settings.
• Multi-Vote — Optionally allow users to vote for multiple options.
• Anonymous Voting — Hide voter identities when privacy matters.
• Time Limits — Set an optional duration in minutes for the poll to auto-close.
• Live Results — Vote counts update in real-time for all participants.
• Close Control — Poll creators and moderators can close a poll early.

Channel Permissions

Fine-grained control over who can see and post in each channel.

• Public / Private — Public channels are visible to everyone. Private channels require explicit membership — non-members can't see or join them.
• Open / Read-Only — Open channels let all members post. Read-only channels restrict posting to moderators and channel moderators.
• Channel Members — Admins, creators, and channel moderators can add and remove members from private channels.
• Channel Moderators — Promote members to channel moderator for per-channel moderation control without granting server-wide mod powers.
• Visual Indicators — Private channels show a lock icon; read-only channels show a muted speaker icon.

Notifications

The notification bell in the navbar keeps you informed of important events:

• Stream Events — Get notified when someone goes live
• Service Alerts — Alerts when managed services crash or restart
• Security Events — Warnings about repeated authentication failures

Click the bell icon to view notifications, and mark them as read individually or all at once.

SSH Keys

Manage SSH key pairs for key-based authentication to your remote servers.

Key Management

• Generate Keys — Create new Ed25519, RSA, or ECDSA key pairs directly in the portal
• Import Keys — Upload existing public keys for use with connections
• Associate with Connections — Link a key pair to an SSH connection for passwordless login

Supported Key Types

API Keys & Authentication

Open Relay Portal supports multiple authentication methods for different use cases.

Authentication Methods

API Key Scopes

When creating an API key, select which features it can access:

• chat — Send and receive chat messages
• stream — Manage streams and stream keys
• connections — Manage user connections
• admin — Admin-level operations (requires admin role)

Two-Factor Authentication (2FA)

Enable TOTP-based two-factor authentication for your account:

1. Go to your profile settings (click your username in the navbar)
2. Click Enable 2FA
3. Scan the QR code with an authenticator app (Google Authenticator, Authy, etc.)
4. Enter the 6-digit code to verify and activate

Once enabled, you'll need to enter a code from your authenticator app each time you log in.

Admin Features ADMIN

Administrators have access to additional tools for managing the portal and monitoring infrastructure.

Service Management

The Services tab on the Dashboard shows two types of services:

• Proxy Services — Route traffic to external backends (e.g., web apps, APIs). Configure host, port, and path.
• Managed Services — Processes that Portal runs directly (e.g., MediaMTX streaming server). Start, stop, restart, and view logs.

Managed services auto-start on boot (if enabled), have health checks every 30 seconds, and auto-restart with exponential backoff on crash.

User Management

• View all registered users and their roles
• Promote or demote user roles
• Reset user passwords
• Ban or disable accounts

Server Terminal

Click the terminal icon in the navbar to open a local shell session directly in your browser. This provides full terminal access to the server running the portal.

Monitoring Tools

VOD Storage

All users can manage their recorded stream archives stored on remote SFTP servers. VODs are automatically recorded as 5-minute MKV chunks during live broadcasts and continuously uploaded to your SFTP storage. When a stream ends, it enters an Encoding state while the final chunk is written and all remaining data is offloaded — the stream only goes fully offline once all VODs are safely stored. Configure your SFTP storage from the My VODs tab, then browse, search, download (individual or batch zip), and delete VOD files.

System Health Dashboard

The Admin Panel includes a real-time system health dashboard showing:

• CPU Usage — Current utilization and load averages
• Memory — Total, used, and available RAM
• Disk — Storage usage for the root partition
• Portal Process — RSS memory, virtual memory, thread count, and PID
• System Uptime — Time since last system boot

Certificate Management

Manage TLS certificates directly from the Admin Panel Settings tab:

• Upload Custom — Bring your own PEM certificate and key (Cloudflare Origin CA, internal CA, etc.)
• Self-Signed — Auto-generate RSA 4096-bit certificates for development or LAN use
• Let's Encrypt — Request free trusted certificates with automated renewal
• Certificate Info — View subject, issuer, SANs, expiry countdown, fingerprint, and key type
• Expiry Warnings — Automatic alerts when certificates are expiring within 30 days
• Apply & Restart — Seamlessly activate new certificates with one click

Setup Wizard

One-command setup from fresh clone to running server:

sudo python3 server.py setup

The setup wizard works immediately on a fresh git clone — no virtual environment or dependencies needed first. It handles everything:

• Auto-generates a self-signed TLS certificate on fresh installs so the server starts immediately
• Creates virtual environment and installs all Python dependencies
• Generates JWT secret and writes .env configuration
• Initializes the database and creates the admin user
• Generates systemd service file with correct paths for any install location
• Optionally installs, enables, and starts the service
• Validates the final configuration (cert files exist, permissions, JWT secret)
• Works for both fresh installs and reconfiguration of existing setups
• Switch to Let's Encrypt or custom certs later via Admin Panel or re-running setup

Data Retention

Configure automatic cleanup policies for old data to keep the database lean. Settings are available in the Admin Panel Settings tab:

Expired tokens and API keys are also cleaned up automatically during each run.

• Automatic Cleanup — Task runs on the configurable interval (default: every 6 hours)
• Manual Trigger — Force cleanup immediately from the Settings tab
• Disable Per-Type — Set days to 0 or max entries to 0 to disable cleanup for that data type

Server File Manager (Admin Panel → Files Tab)

The Admin Panel includes a Files tab for managing local server files:

• Integrated File Browser — Full file manager UI embedded directly in the Admin Panel
• Drag-and-Drop Upload — Drag files from your desktop to upload instantly
• Quick Edit — Edit server configuration files on-the-fly with syntax highlighting
• Path Navigation — Breadcrumb bar for fast directory traversal
• Security — Path traversal prevention, blocked sensitive files (.env, credentials), configurable root directory

Server file management is admin-only and available exclusively in the Admin Panel. The File Manager page (/files) provides Remote Files (SFTP) access for all users.

System Monitor (Admin Panel → System Tab)

Real-time server monitoring and management tools, available in the Admin Panel as the System tab.

Audit Log

A complete, searchable record of all moderation actions on the server. Available to moderators and above in the Admin Panel.

• Comprehensive Tracking — Every mod action is logged: message deletions, timeouts, mutes, bans, channel operations, role changes, and automod triggers.
• Filterable — Filter by action type, actor, channel, or date range to find specific events.
• Paginated — Browse through the full history with pagination support.
• Auto-Cleanup — Configurable retention period (default: 90 days) via the Data Retention settings.
• Privacy — IP addresses are logged for security but not exposed in the API response.

Auto-Moderation

Automated message filtering rules that protect chat channels without requiring moderators to be online. Configure rules in the Admin Panel → Settings tab.

• Word Filter — Block messages containing specific words or patterns. Supports exact match, contains, and regex modes.
• Spam Filter — Detect rapid-fire or duplicate messages with configurable rate limits and duplicate thresholds.
• Link Filter — Control URL posting with allow/block lists or block all links entirely.
• Caps Filter — Prevent excessive caps lock usage above a configurable percentage threshold.
• Mention Spam — Limit the number of @mentions per message to prevent notification abuse.

Automod Actions

• Warn — Send a private error message to the user
• Delete — Silently block the message from being sent
• Timeout — Automatically timeout the user for a configurable duration
• Mute — Automatically mute the user

Moderators, admins, and superadmins bypass all automod rules. All triggers are logged to the audit log.

File Manager

Browse and manage files through the web interface. The File Manager page (/files) provides Remote Files (SFTP) access for all users. Server file management is available in the Admin Panel → Files tab (admin only).

Security

Open Relay Portal is designed with security as a core principle.

Transport Security

• HTTPS Only — All traffic is served over TLS on port 443. No HTTP fallback.
• HSTS — HTTP Strict Transport Security with 1-year max-age, includeSubDomains, and preload.
• WSS Only — All WebSocket connections use TLS encryption.
• TLS 1.2+ — Only strong cipher suites are permitted.
• Voice Encryption — Voice chat audio is encrypted end-to-end via WebRTC DTLS-SRTP. No audio is stored or processed server-side.

Data Protection

• Chat Encryption — Messages are encrypted at rest using Fernet symmetric encryption.
• Password Hashing — All passwords are hashed with Argon2id (memory-hard, timing-safe).
• API Key Storage — API keys are stored as hashed values. Only the prefix is kept for lookup.
• SSH Private Keys — Never stored server-side. Returned once at creation time only.
• RTMP Tokens — Plain RTMP uses temporary single-use tokens instead of permanent stream keys. Tokens expire after 15 minutes and are invalidated immediately on use.
• Log Redaction — Sensitive data (passwords, tokens, keys) is automatically stripped from logs.

Access Controls

• Role-Based Access — Four-tier role system controlling feature access.
• Opaque Connection IDs — Connections use URL-safe tokens instead of sequential integers, preventing enumeration.
• Proxy Isolation — Embedded browser strips Portal session cookies and auth headers from upstream requests. Proxied content runs in a sandboxed iframe.
• Rate Limiting — Per-IP rate limiting on all endpoints to prevent abuse.
• Localhost Blocking — User connections cannot target local addresses (127.0.0.1, ::1).
• CSRF Protection — Secure cookie attributes prevent cross-site request forgery.
• Invite-Only Registration — New accounts require an invite code (daily, single-use, or timed).

Mobile & Accessibility

The portal is fully responsive and optimized for mobile devices, tablets, and desktop browsers.

Responsive Breakpoints

Touch & Accessibility

• 44px Touch Targets — All buttons and interactive elements meet WCAG minimum size on touch devices.
• iOS Zoom Prevention — Form inputs use 16px font to prevent unwanted auto-zoom.
• Reduced Motion — Animations are disabled when the user prefers reduced motion.
• High Contrast — Enhanced borders and contrast in high-contrast mode.
• Focus Indicators — Visible focus rings on all interactive elements for keyboard navigation.